Skip to content

Publish the keyword documentation per version - #3

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

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

Conversation

@MobyNL

@MobyNL MobyNL commented Aug 18, 2026

Copy link
Copy Markdown
Owner

The rendered libdoc page was committed to main and served from the repository root, so there was one page: whatever was newest. Someone on 0.1.0 read 0.2.0's keywords.

What changes

  • .github/workflows/docs.yml generates the page from the library and publishes it to gh-pages: /<version>/GraphQLLibraryKeywords.html per tag, /dev for main, /latest and the bare GraphQLLibraryKeywords.html for the newest release. The bare path is what the metadata of the already published releases points at, so it stays served.
  • tools/build_docs_index.py renders the landing page listing the versions, from a versions.json the workflow maintains on the branch. It sits in the repository rather than inside the workflow so it can be tested, which utest/test_docs_index.py does.
  • GraphQLLibraryKeywords.html, index.html and .nojekyll are no longer committed. A rendered page records 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. Generating on publish leaves nothing that can drift.
  • workflow_dispatch takes a ref, because a dispatch can only run a workflow that exists on the chosen ref and v0.1.0 and v0.2.0 predate this one. Naming the tag publishes it, taking tools/ from main.
  • /latest and the bare path move only when the version being published really is the newest release, so backfilling an old tag cannot point them at older documentation.

After merging

  1. Merging runs the workflow, which creates gh-pages with /dev.
  2. Set Pages to serve from gh-pages, root. It currently serves main, so the documentation URL is broken between the merge and this step.
  3. Run Documentation from main twice, with ref set to v0.1.0 and then v0.2.0, to publish the two existing releases.

Checks

183 unit tests pass (21 of them new), ruff and mypy clean. The publishing steps were run end to end against a throwaway local remote: dev, 0.2.0, 0.1.0, dev again, confirming the site layout, that republishing dev does not accumulate entries, and that backfilling 0.1.0 leaves /latest on 0.2.0.

🤖 Generated with Claude Code

The rendered libdoc page was committed to main and served from the repository root, so
there was one page: whatever was newest. Someone on 0.1.0 read 0.2.0's keywords.

A workflow now generates it and publishes to gh-pages, one directory per release plus
/dev for main, with /latest and the bare path following the newest release - the bare
path is what the metadata of the already published releases points at, so it stays
served. tools/build_docs_index.py renders the landing page from a versions.json the
workflow maintains, and is tested rather than verified by publishing and looking.

The page is no longer committed. It records 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. Generating on publish leaves
nothing that can drift.

workflow_dispatch takes a ref, because a dispatch can only run a workflow that exists
on the chosen ref and v0.1.0 and v0.2.0 predate this one. Naming the tag publishes it.
/latest moves only when the version published is really the newest release, so
backfilling an old tag cannot point it at older documentation.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@MobyNL
MobyNL merged commit dd1c20f into main Aug 18, 2026
11 checks passed
@MobyNL
MobyNL deleted the feat/docs-per-version branch August 18, 2026 19:52
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