Publish the keyword documentation per version - #3
Merged
Conversation
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>
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 rendered libdoc page was committed to
mainand 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.ymlgenerates the page from the library and publishes it togh-pages:/<version>/GraphQLLibraryKeywords.htmlper tag,/devfor main,/latestand the bareGraphQLLibraryKeywords.htmlfor 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.pyrenders the landing page listing the versions, from aversions.jsonthe workflow maintains on the branch. It sits in the repository rather than inside the workflow so it can be tested, whichutest/test_docs_index.pydoes.GraphQLLibraryKeywords.html,index.htmland.nojekyllare 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_dispatchtakes aref, because a dispatch can only run a workflow that exists on the chosen ref andv0.1.0andv0.2.0predate this one. Naming the tag publishes it, takingtools/from main./latestand 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
gh-pageswith/dev.gh-pages, root. It currently servesmain, so the documentation URL is broken between the merge and this step.refset tov0.1.0and thenv0.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,devagain, confirming the site layout, that republishingdevdoes not accumulate entries, and that backfilling0.1.0leaves/lateston0.2.0.🤖 Generated with Claude Code