Skip to content

Publish the keyword documentation per version - #5

Merged
MobyNL merged 1 commit into
mainfrom
docs/publish-per-version
Aug 18, 2026
Merged

Publish the keyword documentation per version#5
MobyNL merged 1 commit into
mainfrom
docs/publish-per-version

Conversation

@MobyNL

@MobyNL MobyNL commented Aug 18, 2026

Copy link
Copy Markdown
Owner

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 — generates MongoDBLibraryKeywords.html with libdoc and publishes 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. Runs on pushes to main, on v* tags and on dispatch, under a concurrency: docs group because publishing rewrites a shared branch.
  • tools/build_docs_index.py — renders the landing page listing the published versions, from the versions.json the 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.
  • A workflow_dispatch ref input, because a dispatch can only run a workflow that exists on the chosen ref and v1.0.0 through v1.2.0 all predate this one. Naming a tag checks it out and takes tools/ from main.

/latest and 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.html and .nojekyll are 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 .nojekyll onto 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

  • The publishing shell steps were run end to end against a throwaway local bare remote — dev, then 1.2.0, then a 1.0.0 backfill, then dev again. dev never touched /latest, the backfill left /latest and the bare path on 1.2.0's page, and republishing dev replaced its entry rather than adding one.
  • ruff, mypy, robocop, 398 unit tests (22 of them new), and the acceptance suite against a local mongodb-atlas-local container: 116 passed, 2 skipped.

After merging

  1. Merge, then let the Documentation run on main create gh-pages.
  2. Switch Pages to serve from the gh-pages branch, root — the docs URL is broken between the merge and that switch, because the files it serves today leave main with this PR.
  3. Dispatch the workflow with ref set to v1.0.0, v1.1.0 and v1.2.0 to backfill the released versions.

🤖 Generated with Claude Code

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>
@MobyNL
MobyNL merged commit ada2f91 into main Aug 18, 2026
12 checks passed
@MobyNL
MobyNL deleted the docs/publish-per-version branch August 18, 2026 21:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant