Docs: migrate versioned-docs publishing to myst-version-switcher assemble model (v0.5.0) - #30
Merged
Merged
Conversation
Replace the legacy peaceiris/actions-gh-pages + keep_files publish (and the
in-repo make_switcher.py) with the version-switcher assemble model, and adopt
the shared `make docs` build used by the other PandABlocks repos:
- ci.yml + _docs.yml + _publish.yml (the documented tutorial split). _docs.yml
drives the build through `make docs` (npx mystmd, pinned by MYSTMD_VERSION in
CONFIG) and packs docs.zip (bare html/ root); _publish.yml runs assemble@v0.5.0
-> upload-pages-artifact -> deploy-pages.
- Add a minimal Makefile + CONFIG.example (the repo had none) exposing the same
`make docs` target; gitignore the local CONFIG copy.
- .devcontainer/Dockerfile (kas-based): add make + npm so `make docs` works in
the container.
- docs/myst.yml: add the version-switcher plugin v0.5.0; add navbar_end.md.
- Publish the `docs` branch as the live version during migration
(guard-default-branch: false; main has no MyST docs yet).
- Remove the old docs.yml and .github/pages/{make_switcher.py,index.html}.
The Pages-source flip + gh-pages backfill/delete are a separate cutover.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
main has no MyST docs build yet, so the assemble model drops /main/. Until docs merges to main, stage the existing gh-pages main/ build into the assemble site dir so generate lists main in switcher.json and /main/ keeps serving. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Migrate versioned-docs publishing to the myst-version-switcher assemble model (
v0.5.0), replacing the legacypeaceiris/actions-gh-pages+keep_filesgh-pages publish and the in-repomake_switcher.py. Also adopts the sharedmake docsbuild used by the other PandABlocks repos.ci.yml+_docs.yml+_publish.yml(the documented tutorial split); build driven throughmake docs, packsdocs.zip(barehtml/root);_publish.ymlrunsassemble@v0.5.0→ deploy.make docstarget; gitignore the localCONFIG.make+npmsomake docsworks in the container.docs/myst.yml: add the version-switcher pluginv0.5.0; addnavbar_end.md. Retire.github/pages/make_switcher.py.docsbranch is published as the live version (guard-default-branch: false).The Pages-source flip +
gh-pagesbackfill/delete are a separate cutover (see the issue).Part of #28. Base:
docs.🤖 Generated with Claude Code