Generate API Documentation

[audionerd]

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:

• Current (released) version at https://stately.ai/api/@xstate/react
• Next (unreleased) version at https://stately.ai/api/@xstate/react/next
• Prior versions at https://stately.ai/api/@xstate/react/{VERSION}

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

• Rush Stack API docs use API Extractor and Docusaurus with the new API Documenter plugin system and a custom plugin
• Puppeteer API docs use API Extractor and Docusaurus with a custom Puppeteer docgen

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

[vercel]

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

A member of the Team first needs to authorize it.

[audionerd]

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:

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]

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

[audionerd]

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]

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