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

• [x] System for generating API Docs
• [x] Fix index page (instead of package listing provide full API table of context)
• [x] Fix sidebar listing (instead of simple filenames provide categorical tree)
• [x] Fix duplicate breadcrumbs (Docusaurus breadcrumbs are showing filename instead of categorical, Markdown breadcrumbs include Home which is confusing)
• [x] 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