Skip to content

Add a version switcher to all docs pages - #35

Open
jorgensd wants to merge 1 commit into
mainfrom
dokken/version-switcher
Open

jorgensd wants to merge 1 commit into
mainfrom
dokken/version-switcher

Conversation

@jorgensd

Copy link
Copy Markdown
Member

Adds a Read-the-Docs-style version dropdown to every page on docs.fenicsproject.org, including old builds and Doxygen pages, without rebuilding anything.

At deploy time, website.yml now:

  • runs make_versions.py, which writes <project>/versions.json from the version folders (main and tags) and marks the newest release as stable
  • runs inject_switcher.py, which adds one <script> line before </body> in each HTML page
  • runs inject_switcher.py --verify ., which fails the job if any published file differs from the repo by more than that line

Only the Pages artifact is modified; nothing is committed back.

The dropdown opens the same page in the selected version. If that page doesn't exist there, it falls back to the nearest parent page, then to python/ or cpp/. dolfinx Doxygen pages map between cpp/ (v0.1–v0.3) and cpp/doxygen/ (v0.4+). Old releases also show a dismissible "newer release available" banner.

  • No existing URL changes. The only new paths are /_fenics/version-switcher.js, /versions.json and /<project>/versions.json.
  • New versions appear automatically when a project's CI pushes its docs.

Tested on a full copy of the site:

  • Injection and verification take about 10 s.
  • The verify step found 0 differences besides the added line.
  • Headless-browser checks passed across all themes and Doxygen versions.

Follow-up: generate the README/index version list from versions.json and remove mark_old_docs.py.

🤖 Generated with Claude Code

This branch has not been deployed

No deployments
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