Publish the keyword documentation per version - #5
Merged
Conversation
The keyword documentation was one committed page served from main, so a reader always got the newest one whatever version they had installed, and the page had to be regenerated and committed by hand before every release. A Documentation workflow now generates it with libdoc and pushes it to the gh-pages branch: /<version>/ per v* tag, /dev for the current main, and /latest plus the bare MongoDBLibraryKeywords.html at the site root for the newest release. The bare path is what the metadata of the already published releases points at, so it stays served. /latest and the bare path only move when the version just published is actually the newest release. The released tags all predate this workflow and have to be backfilled by dispatching it with a ref, and backfilling an old tag must not demote them; tools/build_docs_index.py answers that question through its exit code, and has unit tests, because the workflow runs once per release where a mistake is only noticed after the fact. MongoDBLibraryKeywords.html, index.html and .nojekyll are no longer committed. A rendered libdoc page carries its generation time, the absolute path of the machine that produced it and the Robot Framework and Python versions used, so a committed copy cannot be compared against a freshly generated one. Co-Authored-By: Claude Opus 5 (1M context) <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
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.
The keyword documentation was one committed page served from
main, so a reader always got the newest one whatever version they had installed, and it had to be regenerated and committed by hand before every release.What this adds
.github/workflows/docs.yml— generatesMongoDBLibraryKeywords.htmlwith libdoc and publishes it to thegh-pagesbranch:/<version>/perv*tag,/devfor the current main, and/latestplus the bareMongoDBLibraryKeywords.htmlat the site root for the newest release. The bare path is what the metadata of the already published releases points at, so it stays served. Runs on pushes tomain, onv*tags and on dispatch, under aconcurrency: docsgroup because publishing rewrites a shared branch.tools/build_docs_index.py— renders the landing page listing the published versions, from theversions.jsonthe workflow keeps on the branch.utest/test_docs_index.py— unit tests for it. This code runs once per release, in a workflow, where a mistake is only noticed after the fact and shows up as a broken or misleading site.workflow_dispatchrefinput, because a dispatch can only run a workflow that exists on the chosen ref andv1.0.0throughv1.2.0all predate this one. Naming a tag checks it out and takestools/frommain./latestand the bare path move only when the version just published is actually the newest release, so backfilling an older tag cannot point them at older documentation. The builder answers that through its exit code and the workflow branches on it.MongoDBLibraryKeywords.html,index.htmland.nojekyllare untracked, and the generated page is gitignored: a rendered libdoc page carries its generation time, the absolute path of the machine that produced it and the Robot Framework and Python versions used, so a committed copy cannot be compared against a fresh one. The workflow writes.nojekyllonto the branch itself.The releases before 1.0.0 are not published — they are tagged without a
v, predate the current keyword set, and the landing page footer says so and points at the changelog.Verification
devnever touched/latest, the backfill left/latestand the bare path on 1.2.0's page, and republishingdevreplaced its entry rather than adding one.ruff,mypy,robocop, 398 unit tests (22 of them new), and the acceptance suite against a localmongodb-atlas-localcontainer: 116 passed, 2 skipped.After merging
maincreategh-pages.gh-pagesbranch, root — the docs URL is broken between the merge and that switch, because the files it serves today leavemainwith this PR.refset tov1.0.0,v1.1.0andv1.2.0to backfill the released versions.🤖 Generated with Claude Code