Add auto-generated API documentation #3251
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
The goal of this PR is to create a solution for computer-generated documentation. It includes these pieces:
documentation
dependency to the mono-repo rootyarn docs
at either the root or package levelThe docs aren't super great, but they are a decent start (better than nothing) and they are at least highly searchable.
What this PR means for maintenance is that when someone is doing a version release, they can also update the docs with
yarn docs
This also means that we will need to be more on top of using
/** */
docstrings on everything we want in the API docs.Design choices
I don't know how to design for mono-repos very well yet, so if something I've done is super tacky, let me know what a better way to do it would be. It seems simple and maintainable enough as I've done it.
Docs are put into a /docs folder for github pages compatibility. I figure we can just serve gh-pages out of
main
.Each package will have its own folder in the site, and the script will set the currently generated docs as the default root "latest" (replacing the existing latest) and then also create an archival duplicate under a version-named folder.
Test Plan
Docs viewing
Open the html file you want to look at in a browser
Docs generation script
yarn docs
at root levelyarn docs
at package level