Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate API Documentation #237

Open
wants to merge 44 commits into
base: main
Choose a base branch
from
Open

Conversation

audionerd
Copy link
Contributor

@audionerd audionerd commented Oct 20, 2023

Summary

Provide API documentation for https://stately.ai generated from analysis of the source code and inline comments of XState packages.

For users:

  • Browse XState API docs for the latest version at https://stately.ai/api/xstate
  • Site navbar has an "API" item which links to the XState API docs.

For maintainers:

  • The API Docs can easily be kept up-to-date for each release.

For this PR, our scope is to publish API docs for only the xstate package (packages/core) from the next branch of the xstate repo.

Demo: https://audionerd.github.io/statelyai-docs/api/xstate/xstate

Scope Exclusions

No other packages
Other XState packages, such as @xstate/react, are not included (yet). Their existing handwritten Markdown in docs/ will remain.

No other versions
In future, Docusaurus Multi-Instances could be set up to version the API docs, e.g. for @xstate/react:

No v4 API
XState v4 API docs will not be generated (yet).

No CI or GitHub Actions integration (yet)
Updating API docs will be a manual process (for the first iteration).

Implementation

The xstate package has been added as a submodule in docs.

To generate API docs, before yarn start or yarn build, run:

$ scripts/update-api-docs.sh

This command generates XState API Documentation as Markdown files to the api/xstate directory.

The script uses API Extractor to generate the API documentation by analyzing the TypeScript files and inline comments of a package. It first creates a *.api.json doc model file, which is then used by API Documenter to generate Markdown files. We use the Docusaurus Multi-Instance feature to configure the api/xstate directory of Markdown files as its own docs instance, and the same approach can be used to support versioned docs for all XState packages in the future.

The generated Markdown files will be checked into the docs repo so that updates to non-API docs can happen quickly, without running the update-api-docs script again.

Risks

API Extractor assumes inline comments are in TSDoc format, which differs somewhat from the JSDoc currently used by XState. If switching to TSDoc is problematic, TypeDoc and this TypeDoc Docusaurus plugin could be considered instead of API Extractor.

Reference

Tasks

  • System for generating API Docs
  • Fix index page (instead of package listing provide full API table of context)
  • Fix sidebar listing (instead of simple filenames provide categorical tree)
  • Fix duplicate breadcrumbs (Docusaurus breadcrumbs are showing filename instead of categorical, Markdown breadcrumbs include Home which is confusing)
  • Commit generated Markdown files (waiting to do this until the overall approach is approved)
  • Update README with git submodule init and update instructions

Future work

  • Algolia integration: ability to search API docs (e.g.: press Cmd+K, type "fromCallback", see result, view docs for the function)
  • setup the other XState packages (e.g.: @xstate/react) and provide a list of all packages at /api/index.md
  • write a script to generate api docs for the most recent version of all XState packages, not just XState core

- next at /api/xstate/next
- latest 5.1.0 at /api/xstate
- archived 5.0.0 at /api/xstate/5.0.0
the breadcrumbs generated in Markdown by api-documenter are more precise
without this, api extractor will find package.json a level up and use the name/canonicalReference "stately-docs" instead of "xstate"
@vercel
Copy link

vercel bot commented Oct 20, 2023

@audionerd is attempting to deploy a commit to the Stately Team on Vercel.

A member of the Team first needs to authorize it.

@audionerd
Copy link
Contributor Author

audionerd commented Oct 20, 2023

Re: the sidebar, I have an unfinished API Documenter plugin based on this example which outputs
sidebar config as a categorical tree and has a hacky fix for better breadcrumbs. Ran out of time this week but I can share that code too. Looks like:

api-with-sidebar

If that can be finished up and added then the docs will be pretty usable.

Takes advantage of API Documenter's generate feature and its plugin system, more info here: https://api.rushstack.io/pages/api-documenter

@audionerd
Copy link
Contributor Author

Note that the Docusaurus build will fail unless you make this tweak first: statelyai/xstate#4374

@audionerd
Copy link
Contributor Author

audionerd commented Oct 23, 2023

API Documenter offers a new plugin system which we can use to customize its output for better display in Docusaurus, both for its generated Markdown and to generate a sidebar.

Using this Rush Stack example as a guide, I set up a basic plugin specific to XState and Docusaurus which is run by api-documenter generate as configured in api-documenter.json.

Demo here: https://audionerd.github.io/statelyai-docs/api/xstate

With this change, the API Doc output and sidebar are usable, and the generated URLs should be stable enough to rely on moving forward.

@audionerd
Copy link
Contributor Author

Will probably use JSDoc and TypeDoc instead of TSDoc and API Documenter.

API Documenter requires TSDoc, but Visual Studio Code IntelliSense does not really understand TSDoc, leading to confusing rendering in the editor. API Documenter is missing a few important conversions from TSDoc to Markdown (e.g.: no support for Markdown lists or @see).

PR for TypeDoc plugin setup is here: #288

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant