Replace sphinx-multiversion with per-branch docs builds

[AntoineRichard]

Summary

Same changes as the develop PR (#5226), applied to main's diverged files.

• Removes sphinx-multiversion from docs build
• Each deploy branch builds only its own docs
• Adds version switcher (theme built-in + injected JS for old versions)
• Adds one-time docs-migration.yaml workflow
• Pins sphinx>=7.0,<9 and sphinx-book-theme>=1.1 (supersedes Pin Sphinx <9 on main for sphinx-multiversion compatibility #5223)

See spec: docs/superpowers/specs/2026-04-10-multi-version-docs-design.md

Test plan

• Docs CI builds successfully on this PR
• After merge, verify docs deploy correctly for main

[greptile-apps]

Greptile Summary

This PR replaces sphinx-multiversion with a per-branch docs-build approach: each branch/tag builds only its own docs, a custom JavaScript version switcher + the pydata-sphinx-theme built-in switcher provide navigation across versions, and a one-time migration workflow (docs-migration.yaml) rebuilds all historical versions.

• Race condition in versions.json update (docs.yaml, lines 141–196): the deploy job fetches the live versions.json, adds the current branch's entry, and force-pushes. Two concurrent deploys (e.g. a release tag and main merging simultaneously) will each start from the same stale JSON and whichever push wins will silently drop the other branch's entry from the version switcher.
• DOCS_VERSION_SLUG not set in migration workflow (docs-migration.yaml, lines 76–81): branches with the new conf.py (main, develop, release branches) will build with version_match falling back to the semver string instead of the directory slug, so the built-in theme switcher will not highlight the current version.

Confidence Score: 4/5

Functionally sound for single-branch deploys, but has a real race condition that can silently drop version entries from the switcher when two branches deploy concurrently

Two P1 findings: a fetch-mutate-push race on versions.json and the missing DOCS_VERSION_SLUG in the migration workflow. The race is unlikely in normal operation but is a true correctness bug when it does occur, and the missing env var will cause incorrect version highlighting for every branch built during migration.

.github/workflows/docs.yaml (race condition in versions.json update) and .github/workflows/docs-migration.yaml (missing DOCS_VERSION_SLUG env var)

Important Files Changed

Filename	Overview
.github/workflows/docs.yaml	New per-branch deploy workflow; has a race condition in the versions.json upsert step and dead code in the NAME assignment block
.github/workflows/docs-migration.yaml	One-time migration workflow that rebuilds all historical docs; missing DOCS_VERSION_SLUG env var for recent branches causes wrong version_match in the built-in switcher
docs/_static/version-switcher.js	New standalone version switcher injected into old docs that lack the theme built-in; path parsing assumes /project/version/ URL structure, which is correct for the current gh-pages setup
docs/conf.py	Removes sphinx_multiversion extension, adds pydata-sphinx-theme built-in version switcher with DOCS_VERSION_SLUG env-var fallback; clean change
docs/requirements.txt	Drops sphinx-multiversion, pins sphinx>=7.0,<9 and sphinx-book-theme>=1.1 for version-switcher support
docs/Makefile	Adds current-docs target that builds into _build/current, used by docs.yaml CI
docs/_templates/versioning.html	Deleted sphinx-multiversion sidebar template, superseded by the theme built-in and standalone JS switcher

Sequence Diagram

sequenceDiagram
    participant GH as GitHub Push (branch/tag)
    participant CI as docs.yaml CI
    participant Pages as gh-pages
    participant Site as Live Site

    GH->>CI: trigger on push
    CI->>CI: build docs (sphinx-build)
    CI->>CI: set DOCS_VERSION_SLUG
    CI->>Pages: download existing versions.json
    Pages-->>CI: versions.json (may be stale)
    CI->>CI: upsert current version entry
    CI->>Pages: deploy site/SLUG/ + versions.json (keep_files: true)
    Pages-->>Site: updated versions.json + versioned docs

    Note over CI,Pages: Race: two concurrent pushes both read stale JSON and overwrite each other

    participant Mig as docs-migration.yaml
    Note over Mig: One-shot: rebuilds all historical versions
    Mig->>Mig: matrix build all refs
    Mig->>Pages: deploy full site (keep_files: false - full reset)

Loading

_{Reviews (1): Last reviewed commit: "Replace sphinx-multiversion with per-bra..." | Re-trigger Greptile}

[greptile-apps]

Race condition in versions.json upsert

Two concurrent deploys (e.g. a release tag and main merging in quick succession) each fetch the live versions.json, compute their own updated copy independently, and force-push. Whichever push lands second silently overwrites the first, dropping the other branch's entry from the version switcher for all users until that branch deploys again.

The fetch → mutate → push pattern is inherently racy without a lock or atomic update mechanism. Consider using a dedicated gh-pages-update workflow triggered serially (e.g. via workflow_run with concurrency: group: versions-json, cancel-in-progress: false) or generating versions.json from the directory listing of the deployed site inside the push step rather than before it.

[greptile-apps]

DOCS_VERSION_SLUG not passed to migration builds

For branches that already carry the updated conf.py (main, develop, release/2.1.0, release/2.2.0, release/2.3.0), _version_slug will fall back to the semver from the VERSION file (e.g. "3.0.0") instead of the directory slug (e.g. "main"). The pydata-sphinx-theme built-in switcher uses version_match to highlight the current version; a mismatch means no version is highlighted and users lose orientation. The regular docs.yaml sets this variable correctly:

Suggested change

	- name: Build docs
	working-directory: ./docs
	# No -W flag: old versions may have warnings that are acceptable.
	run: |
	rm -rf "_build"
	sphinx-build -b html . "_build"
	- name: Build docs
	working-directory: ./docs
	env:
	DOCS_VERSION_SLUG: ${{ steps.slug.outputs.slug }}
	# No -W flag: old versions may have warnings that are acceptable.
	run: |
	rm -rf "_build"
	sphinx-build -b html . "_build"

[greptile-apps]

Dead conditional — both branches assign the same value

Both arms of the if/else set NAME="${SLUG}", so the condition is never meaningful. The block can be simplified or removed entirely.

Suggested change

	REF="${{ github.ref }}"
	if [[ "$REF" == refs/tags/* ]]; then
	NAME="${SLUG}"
	else
	NAME="${SLUG}"
	fi
	NAME="${SLUG}"

[kellyguo11]

Review: Replace sphinx-multiversion with per-branch docs builds

Good direction — sphinx-multiversion has been unmaintained since 2020 and has been a recurring source of build pain. Per-branch builds are simpler, more reliable, and easier to reason about. This mirrors the same approach as #5226 on develop, applied to main's diverged files.

CI Status

Both CI failures are pre-existing / not caused by this PR:

1. Docs build failure — 18 autosummary.import_cycle warnings (pre-existing on main) treated as errors by -W. Additionally, the pydata-sphinx-theme version switcher tries to fetch versions.json at build time and logs a warning when it 404s (expected — the file won't exist until the first deploy). The previous PR #5223 added suppress_warnings = ["autosummary.import_cycle"] to conf.py but this PR doesn't include that suppression. Since this PR says it supersedes #5223, it should carry forward the warning suppression.

2. Link checker failure — https://graphics.pixar.com/usd/docs/index.html returns 404. Pre-existing, unrelated to this PR.

Issues

Should-fix:

1. Missing suppress_warnings for autosummary.import_cycle — PR #5223 (which this supersedes) added suppression for these warnings. Without it, the -W flag in make current-docs will keep failing on main. Need to add suppress_warnings = ["autosummary.import_cycle"] to conf.py or the build will never pass.

2. versions.json 404 warning breaks -W build — When building locally or in CI before the first deploy, the pydata-sphinx-theme version switcher fetches versions.json and emits a warning on 404. With -W (warnings as errors), this is fatal. Consider either:

   • Suppressing this specific warning category in conf.py
   • Adding a placeholder versions.json to the repo
   • Or documenting that the first build will need -W relaxed

3. Shell injection risk in docs.yaml deploy step — The SLUG variable is interpolated directly into shell via ${SLUG} in the "Assemble deploy directory" and "Update versions.json" steps. While the branch/tag names are constrained by the workflow trigger patterns, the Python script uses '${SLUG}' and '${NAME}' (single-quoted shell substitution inside a Python heredoc), which could break if a tag/branch name contains single quotes. Consider passing these as environment variables that Python reads via os.environ instead.

4. docs-migration.yaml uses actions/download-artifact@v8 — This action version doesn't exist yet (current latest is v4). The main docs.yaml also uses @v7 for upload and @v8 for download. These should be pinned to actually-released versions (v4 for both).

5. actions/checkout@v6 doesn't exist — Current latest is v4. Both workflow files reference @v6. This will cause the workflows to fail.

Suggestions:

6. Duplicate slug determination logic — The "Determine version slug" step appears in both build-docs and deploy-docs jobs in docs.yaml with identical logic. Consider extracting it once and passing via job outputs, or at minimum adding a comment noting the intentional duplication.

7. Migration workflow actions/upload-artifact@v7 — Same version concern as above; should be @v4.

8. XHR in version-switcher.js — XMLHttpRequest is legacy. Since this is new code, consider using fetch() with a fallback, or just fetch() since all modern browsers support it. Not blocking, but the code would be cleaner.

9. HEAD request for page existence check — The version switcher does a HEAD request to check if a page exists in the target version before navigating. This is a nice UX touch, but be aware some CDN/hosting setups don't handle HEAD well for static files. A comment explaining the fallback behavior would help future maintainers.

10. devel → develop rename in trigger — The workflow trigger changes devel to develop. Make sure all references to the old branch name are cleaned up across the repo (not just this file).

Overall

Solid architectural improvement. The standalone version-switcher.js approach is clever — it allows injecting version switching into old builds that never had it. The migration workflow for one-time historical rebuild is well thought out.

Main blockers are the action version references (v6/v7/v8 don't exist) and the missing warning suppression from #5223. Fix those and this is good to go.

[kellyguo11]

This PR supersedes #5223, which added suppress_warnings = ["autosummary.import_cycle"] to fix the 18 import_cycle warnings that break -W builds on main. That suppression isn't carried forward here, so the docs build will continue to fail.

Also, the pydata-sphinx-theme version switcher emits a warning when versions.json returns 404 (which it will until first deploy), adding another -W failure.

Suggestion: add the suppression from #5223 here too:

suppress_warnings = ["autosummary.import_cycle"]

And consider suppressing the version-switcher fetch warning as well, or providing a placeholder versions.json.

[kellyguo11]

Both actions/checkout@v6 and actions/upload-artifact@v7 / actions/download-artifact@v8 referenced in this workflow don't exist yet. Current latest versions are @v4 for all of these. The workflow will fail to run as-is.

Same issue in docs-migration.yaml.

[kellyguo11]

The SLUG and NAME variables are interpolated into the Python heredoc via '${SLUG}' / '${NAME}'. If a branch/tag name ever contains a single quote, this breaks the Python string literal. Safer approach:

import os
slug = os.environ['SLUG']
name = os.environ['NAME']

(with SLUG and NAME passed as env vars to the step, which you already have for SLUG).

[github-actions]

Test Results Summary

3 687 tests   3 158 ✅  2h 28m 40s ⏱️
  119 suites    528 💤
    1 files        0 ❌  1 🔥

For more details on these errors, see this check.

Results for commit e864af5.

♻️ This comment has been updated with latest results.

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot

Summary

This PR replaces the unmaintained sphinx-multiversion with a per-branch/per-tag docs build strategy. Each push to main, develop, release/**, or a version tag builds only its own docs and deploys to a versioned subdirectory on gh-pages. A standalone version-switcher.js is injected into all versions (including historical ones via a one-time migration workflow) to provide cross-version navigation. The approach is sound and the implementation is well-structured.

Design Assessment

Design is sound. Replacing sphinx-multiversion with per-branch builds is the right call — sphinx-multiversion has been unmaintained since 2020, requires fetching all branches to build any version, and causes frequent CI pain. The new approach is simpler, faster (each version builds independently), and the injected JS switcher elegantly handles backward compatibility with old versions that never had a version dropdown. The concurrency serialization on the deploy job prevents race conditions on versions.json. Good engineering.

Findings

🟡 Warning: Hardcoded /IsaacLab/ path prefix throughout — Multiple files

The repo name IsaacLab is hardcoded in several places:

• docs-migration.yaml:128 — sed injection: <script src="https://github.com/IsaacLab/version-switcher.js">
• docs-migration.yaml:160 — versions.json URL entries: '/IsaacLab/' + name + '/'
• docs.yaml:154 — same sed injection
• docs.yaml:196 — same URL pattern
• version-switcher.js:30 — comment says "Works for both /IsaacLab/main/... and custom domain setups" but the path-parsing logic assumes a /project/version/... URL structure that would break on a custom domain (where there's no project prefix)
• conf.py:305 — json_url uses the full GitHub Pages URL

If this repo is ever renamed or the docs move to a custom domain, all of these break silently. Consider extracting the base path as a workflow-level variable (e.g., DOCS_BASE_PATH: /IsaacLab/) and passing it through, at least for the workflow files. The JS comment on line 30 of version-switcher.js should also be corrected — it does not currently work for custom domain setups.

🟡 Warning: Unpinned upper bound on sphinx-book-theme — docs/requirements.txt:3

The change from sphinx-book-theme==1.0.1 to sphinx-book-theme>=1.1 with no upper bound means a future major version bump could break docs builds without any change to this repo. sphinx>=7.0,<9 has a sensible upper bound; sphinx-book-theme should follow the same pattern:

sphinx-book-theme>=1.1,<2

🔵 Suggestion: version-switcher.js uses XMLHttpRequest instead of fetch — docs/_static/version-switcher.js

Since this is brand new code, consider using fetch() instead of XMLHttpRequest. All browsers that support ES5 strict mode (which this code uses) also support fetch(). The HEAD request for page-existence checking (lines 66-75) and the GET for versions.json (lines 101-116) would both be cleaner with fetch. Not blocking, but it would reduce the code by ~30%.

🔵 Suggestion: Duplicate slug-determination logic — .github/workflows/docs.yaml

The "Determine version slug" step appears twice in docs.yaml — once in build-docs (lines 59-74) and again in deploy-docs (lines 112-126) with identical logic. Since the build job already computes the slug, consider passing it as a job output to avoid the duplication and potential for the two copies to drift:

outputs:
  slug: ${{ steps.slug.outputs.slug }}

🔵 Suggestion: Migration workflow matrix could be auto-discovered — .github/workflows/docs-migration.yaml

The migration workflow hardcodes 22 refs in the matrix. If a new release is cut before migration runs, it'll be missed. A minor concern since this is a one-time workflow, but worth a comment in the file noting that the matrix should be updated if new releases are created before the migration is executed.

Test Coverage

This is a documentation/infrastructure change with no runtime code changes.

• Docs CI (Build Docs): ✅ Passes — the make current-docs target builds successfully with the new configuration.
• Warning suppressions: Properly added for autosummary.import_cycle and config.invalid_switcher_json, preventing -W failures.
• Manual test plan: PR includes two test items (CI builds, post-merge deploy verification) which are appropriate for this type of change.
• No new runtime tests needed — this affects only the docs build pipeline, not the simulation framework.

CI Status

• ✅ Build Docs — passes
• ✅ pre-commit, license-check, labeler, test-general, test-isaaclab-tasks — pass
• ❌ Check for Broken Links — pre-existing failure (Pixar USD docs URL returns 404), unrelated to this PR
• ❌ Tests Summary / combine-results / Build and Test Results — 1 test failure out of 2,952, pre-existing on main, unrelated to this PR
• ⏭️ Deploy Docs — skipped (expected for PRs, only runs on push to deploy branches)

Verdict

COMMENT

This is a well-designed infrastructure improvement. The only actionable item is pinning sphinx-book-theme's upper bound to prevent future surprise breakage. The hardcoded paths are a maintenance concern but not blocking given the current deployment target is fixed. The remaining suggestions are quality improvements that can be addressed at the author's discretion.

[isaaclab-review-bot]

🟡 Warning: Unpinned upper bound — a future sphinx-book-theme 2.x release could break docs builds without any change to this repo. Consider:

Suggested change

	sphinx-book-theme>=1.1
	sphinx-book-theme>=1.1,<2

[isaaclab-review-bot]

🔵 Suggestion: This comment is misleading — the path-parsing logic below assumes a /<project>/<version>/... URL structure (extracting pathParts[0] as the project and pathParts[1] as the version slug). On a custom domain without a project prefix (e.g., docs.example.com/main/...), pathParts[0] would be the version, not the project, and basePath would be wrong.

Consider updating the comment to:

Suggested change

	var JSON_URL = basePath + "versions.json";
	// Works for GitHub Pages at /<project>/<version>/... URL structure.