Check for duplicates
Problem
Right now deploying documentation always regenerates the reference docs and updates them as well. This is problematic if main contains changes that haven't been released yet, as those unreleased APIs will show up in reference docs. But at the same time, we need flexibility to update the guides in between releases.
Request
Don't update the reference docs when deploying docs (unless we've just done a release / may need to manually specify)
Current flow:
- api-extractor creates an api.json file (gitignored)
- api-documenter uses that to create >4000 mdx files (gitignored)
- docusaurus uses those + handwritten guides to create docs site
- docs site hosted on cloudflare pages
I think that the way Cloudflare pages works is that you upload everything at once, there's no partial update mechanism where if you just don't change some files they stay the same. So I see two paths forward:
Option 1: Commit api.json (preferred)
As part of the release process, commit the api.json file that api-extractor outputs (possibly with a few additional steps that modify the api.json file such as removeRenames in the docs_tasks). Only do this for latest tagged releases, not betas
This file becomes a committed history of our public API shape, which is something we've been interested in anyway since part of the cool thing about using api-extractor is being able to tell when a PR modifies the public API for example.
Then the docs deploy process can generate the reference docs using api-documenter from the committed api.json file instead of re-running api-extractor on the current codebase.
Option 2: Checkout released version of blockly for the reference docs
As part of the release process, find the latest version tag, check that out, run npm run docs on that, and then use those generated reference docs instead of the ones from the current codebase
This would also be fine, but it lacks some of the advantages of the first one:
- no committed api.json file (which again is something we've discussed doing anyway)
- you'd be running the checked-out version of
npm run docs on it so if you wanted to do something like fix a bug in the generated mdx or update the api-documenter patch, you'd have to wait until the next release. with option 1 you can use an updated api-documenter process but keep using the old api.json surface without doing a release
option 3: commit all the generated reference docs (not recommended)
just including this here to document all the options, we could commit all the reference docs to the repo instead of generating them at documentation deploy time. but that would also still need to be done only at release time to avoid the original problem of documenting unreleased APIs, so it is just a more cumbersome version of option 1 that requires us to commit a bunch of files that may change just for cosmetic reasons in between releases.
Alternatives considered
No response
Additional context
No response
Check for duplicates
Problem
Right now deploying documentation always regenerates the reference docs and updates them as well. This is problematic if
maincontains changes that haven't been released yet, as those unreleased APIs will show up in reference docs. But at the same time, we need flexibility to update the guides in between releases.Request
Don't update the reference docs when deploying docs (unless we've just done a release / may need to manually specify)
Current flow:
I think that the way Cloudflare pages works is that you upload everything at once, there's no partial update mechanism where if you just don't change some files they stay the same. So I see two paths forward:
Option 1: Commit api.json (preferred)
As part of the release process, commit the api.json file that api-extractor outputs (possibly with a few additional steps that modify the api.json file such as
removeRenamesin the docs_tasks). Only do this forlatesttagged releases, not betasThis file becomes a committed history of our public API shape, which is something we've been interested in anyway since part of the cool thing about using api-extractor is being able to tell when a PR modifies the public API for example.
Then the docs deploy process can generate the reference docs using api-documenter from the committed api.json file instead of re-running api-extractor on the current codebase.
Option 2: Checkout released version of blockly for the reference docs
As part of the release process, find the latest version tag, check that out, run
npm run docson that, and then use those generated reference docs instead of the ones from the current codebaseThis would also be fine, but it lacks some of the advantages of the first one:
npm run docson it so if you wanted to do something like fix a bug in the generated mdx or update the api-documenter patch, you'd have to wait until the next release. with option 1 you can use an updated api-documenter process but keep using the old api.json surface without doing a releaseoption 3: commit all the generated reference docs (not recommended)
just including this here to document all the options, we could commit all the reference docs to the repo instead of generating them at documentation deploy time. but that would also still need to be done only at release time to avoid the original problem of documenting unreleased APIs, so it is just a more cumbersome version of option 1 that requires us to commit a bunch of files that may change just for cosmetic reasons in between releases.
Alternatives considered
No response
Additional context
No response