Add multi-version documentation build support#234
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds infrastructure for building and serving Sphinx documentation across multiple Git refs (tags/branches), including a root redirect to the latest version and CI adjustments in preparation for multi-version builds.
Changes:
- Introduces scripts to generate
versions.jsonand to filter a set of versions to keep. - Adds a root
index.htmlredirect template and a redirect JS asset for multi-version docs. - Extends docs Makefile and updates CI workflow setup (full git history + caching), with a commented “Phase 2” multi-version job.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/source/conf.py | Adds sphinx-multiversion config and adjusts HTML output settings. |
| docs/source/_templates/index.html | Adds root redirect page template to send users to latest docs version. |
| docs/source/_static/version-redirect.js | Adds redirect JS (currently not wired into build). |
| docs/scripts/generate_versions_json.py | Generates versions metadata from built output directories. |
| docs/scripts/build_versions.py | Provides helper logic to filter versions by a buffer size. |
| docs/Makefile | Adds multiversion, clean-multiversion, and preview targets. |
| .github/workflows/main.yml | Adds full-history checkout + caches; leaves multi-version build job commented. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| """Helper script for filtering versions to maintain buffer size.""" | ||
|
|
||
| import re | ||
| from pathlib import Path |
Comment on lines
+53
to
+57
| releases.sort(key=parse_version, reverse=True) | ||
|
|
||
| # Keep latest (buffer_size - 1) releases | ||
| releases_to_keep = releases[: (buffer_size - 1)] | ||
|
|
Comment on lines
+68
to
+73
| # -- sphinx-multiversion configuration ------------------------------------------------- | ||
| # Enable multi-version builds (set to True in v0.2.0+) | ||
| ENABLE_MULTI_VERSION = True | ||
|
|
||
| html_theme = "sphinx_book_theme" | ||
| html_static_path = ["_static"] | ||
| # html_logo = "_static/logo_e.png" | ||
| # Version buffer size: number of releases to keep + main branch | ||
| VERSION_BUFFER_SIZE = 5 |
| .PHONY: preview | ||
| preview: | ||
| @echo "Starting documentation preview server at http://localhost:8000" | ||
| @python3 preview.py --directory "$(BUILDDIR)/html" --port 8000 --open |
Comment on lines
72
to
+82
| @@ -56,14 +77,73 @@ jobs: | |||
| echo "Start Building docs..." | |||
| pip uninstall pymeshlab -y | |||
| pip install pymeshlab==2023.12.post3 | |||
| # Build main branch only (Phase 1) | |||
| make html | |||
|
|
|||
Comment on lines
+88
to
+89
| # Don't include version-redirect.js automatically - we add it manually to root | ||
| html_js_files = [] |
| """Generate versions.json for multi-version documentation.""" | ||
|
|
||
| import json | ||
| import os |
Comment on lines
+53
to
+72
| # Sort versions (main last, releases in descending order - newest first) | ||
| def version_key(v): | ||
| name = v["name"] | ||
| if name == "main": | ||
| return (2, "") # Put main last | ||
| else: | ||
| # Extract version number for sorting (v0.1.3 -> (0, 1, 3)) | ||
| parts = name.lstrip("v").split(".") | ||
| try: | ||
| major, minor, patch = map(int, parts[:3]) | ||
| # Use negative for descending sort (newest first) | ||
| return (1, (-major, -minor, -patch)) | ||
| except (ValueError, IndexError): | ||
| return (1, (0, 0, 0)) | ||
|
|
||
| versions.sort(key=version_key) | ||
|
|
||
| return { | ||
| "versions": versions, | ||
| "latest": versions[0]["name"] if versions else "main", |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds infrastructure for building and serving Sphinx documentation across multiple git refs (tags/branches), including a root-level redirect to the “latest” docs and supporting build scripts/CI plumbing.
Changes:
- Added scripts to build/version docs outputs and generate a
versions.jsonmanifest. - Updated Sphinx config + added a root
index.htmlredirect template/static assets for version-aware navigation. - Extended docs Makefile and CI workflow to support (or prepare for) multi-version builds.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
embodichain/lab/sim/robots/cobotmagic.py |
Formatting-only change in default cfg construction. |
docs/source/conf.py |
Adds/updates sphinx-multiversion + HTML context/theme options relevant to versioned docs. |
docs/source/_templates/index.html |
New root HTML redirect page that reads versions.json to send users to the latest docs. |
docs/source/_static/version-redirect.js |
New redirect helper JS (currently appears unused/duplicated). |
docs/scripts/generate_versions_json.py |
New script to generate versions.json from built output directories. |
docs/scripts/build_versions.py |
New helper for filtering versions to a fixed buffer size. |
docs/Makefile |
Adds multiversion, clean-multiversion, and preview targets. |
.github/workflows/main.yml |
Updates docs build job (full checkout + caching) and scaffolds a commented multi-version job. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+68
to
+72
| versions.sort(key=version_key) | ||
|
|
||
| return { | ||
| "versions": versions, | ||
| "latest": versions[0]["name"] if versions else "main", |
| """Generate versions.json for multi-version documentation.""" | ||
|
|
||
| import json | ||
| import os |
| """Helper script for filtering versions to maintain buffer size.""" | ||
|
|
||
| import re | ||
| from pathlib import Path |
Comment on lines
+68
to
+73
| # -- sphinx-multiversion configuration ------------------------------------------------- | ||
| # Enable multi-version builds (set to True in v0.2.0+) | ||
| ENABLE_MULTI_VERSION = True | ||
|
|
||
| html_theme = "sphinx_book_theme" | ||
| html_static_path = ["_static"] | ||
| # html_logo = "_static/logo_e.png" | ||
| # Version buffer size: number of releases to keep + main branch | ||
| VERSION_BUFFER_SIZE = 5 |
Comment on lines
+96
to
+100
| # HTML context for better path handling | ||
| html_context = { | ||
| "github_user": "dexforce", | ||
| "github_repo": "EmbodiChain", | ||
| "github_version": "main", |
Comment on lines
+1
to
+14
| /** | ||
| * Version redirect script for multi-version documentation. | ||
| * Redirects to the latest stable release version, or falls back to 'main'. | ||
| */ | ||
|
|
||
| (function() { | ||
| 'use strict'; | ||
|
|
||
| // Try to fetch versions.json (generated by generate_versions_json.py) | ||
| fetch('versions.json') | ||
| .then(response => { | ||
| if (!response.ok) { | ||
| throw new Error('versions.json not found'); | ||
| } |
Comment on lines
72
to
+82
| @@ -56,14 +77,73 @@ jobs: | |||
| echo "Start Building docs..." | |||
| pip uninstall pymeshlab -y | |||
| pip install pymeshlab==2023.12.post3 | |||
| # Build main branch only (Phase 1) | |||
| make html | |||
|
|
|||
Contributor
There was a problem hiding this comment.
Pull request overview
Adds Sphinx multi-version documentation build support (sphinx-multiversion) including version-selection UI, redirect behavior, build scripts/targets, and CI updates to build/deploy docs with version awareness.
Changes:
- Configure Sphinx for sphinx-multiversion and add a sidebar version selector template.
- Add tooling for version metadata/redirects plus Makefile targets for multi-version and single-version builds.
- Update CI workflow to fetch full git history, build docs (conditionally), and deploy GitHub Pages artifacts.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/source/conf.py | Adds sphinx-multiversion config and sidebar/template integration. |
| docs/source/_templates/versioning.html | Introduces a dropdown UI for switching between built versions. |
| docs/source/_templates/index.html | Adds a root index redirect page for the built docs site. |
| docs/source/_static/version-redirect.js | Adds a JS-based redirect mechanism intended to use versions metadata. |
| docs/scripts/generate_versions_json.py | Adds a script to generate a versions.json metadata file from build output. |
| docs/scripts/build_versions.py | Adds a helper script intended to filter versions to keep. |
| docs/requirements.txt | Pins sphinx-multiversion dependency version. |
| docs/Makefile | Adds multiversion and current-docs targets for new workflows. |
| .github/workflows/main.yml | Updates docs build/deploy logic and adds caching + full checkout history for multiversion builds. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+53
to
+73
| # Sort versions (main last, releases in descending order - newest first) | ||
| def version_key(v): | ||
| name = v["name"] | ||
| if name == "main": | ||
| return (2, "") # Put main last | ||
| else: | ||
| # Extract version number for sorting (v0.1.3 -> (0, 1, 3)) | ||
| parts = name.lstrip("v").split(".") | ||
| try: | ||
| major, minor, patch = map(int, parts[:3]) | ||
| # Use negative for descending sort (newest first) | ||
| return (1, (-major, -minor, -patch)) | ||
| except (ValueError, IndexError): | ||
| return (1, (0, 0, 0)) | ||
|
|
||
| versions.sort(key=version_key) | ||
|
|
||
| return { | ||
| "versions": versions, | ||
| "latest": versions[0]["name"] if versions else "main", | ||
| } |
Comment on lines
+4
to
+7
| <title>Redirecting to the latest EmbodiChain documentation</title> | ||
| <meta charset="utf-8"> | ||
| <meta http-equiv="refresh" content="0; url=./main/index.html"> | ||
| </head> |
Comment on lines
+69
to
+74
| # Whitelist pattern for remotes | ||
| smv_remote_whitelist = r"^origin$" | ||
| # Whitelist pattern for branches (set to None to ignore all branches) | ||
| smv_branch_whitelist = os.getenv("SMV_BRANCH_WHITELIST", r"^main$") | ||
| # Whitelist pattern for tags (set to None to ignore all tags) | ||
| smv_tag_whitelist = os.getenv("SMV_TAG_WHITELIST", r"^v\d+\.\d+\.\d+$") |
Comment on lines
+21
to
+26
| const currentPath = window.location.pathname; | ||
|
|
||
| // If we're at root, redirect to latest version | ||
| if (currentPath === '/' || currentPath.endsWith('/index.html') || currentPath.endsWith('/')) { | ||
| window.location.href = latestVersion + '/'; | ||
| } |
| """Generate versions.json for multi-version documentation.""" | ||
|
|
||
| import json | ||
| import os |
| """Helper script for filtering versions to maintain buffer size.""" | ||
|
|
||
| import re | ||
| from pathlib import Path |
|
|
||
| - name: Upload docs artifact | ||
| if: github.event_name == 'push' && github.ref == 'refs/heads/main' | ||
| if: github.event_name == 'push' |
| NVIDIA_DRIVER_CAPABILITIES: all | ||
| NVIDIA_VISIBLE_DEVICES: all | ||
| NVIDIA_DISABLE_REQUIRE: 1 | ||
| DOCS_VERSIONS: "main,v0.2.0" # Versions to include in multi-version build |
| @rm -rf "$(BUILDDIR)/html" | ||
| @echo "Building multi-version documentation..." | ||
| @sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) | ||
| @cp "$(SOURCEDIR)/_templates/index.html" "$(BUILDDIR)/html/index.html" |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a manual multi-version documentation build/publish approach (replacing sphinx-multiversion) by building each version into its own subdirectory and generating a shared versions.json plus a root redirect to the “latest” docs.
Changes:
- Adds scripts to generate a versions manifest and root redirect, plus helpers for version retention.
- Updates Sphinx configuration/templates to display a version selector in the sidebar.
- Extends the GitHub Actions workflow and docs Makefile/docs instructions for multi-version builds.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/source/quick_start/docs.md | Updates docs build instructions for local and multi-version workflows. |
| docs/source/conf.py | Adjusts Sphinx HTML config and sidebar composition to include a version selector. |
| docs/source/_templates/versioning.html | Adds a custom sidebar template implementing the version dropdown populated from versions.json. |
| docs/source/_templates/index.html | Adds a redirect HTML template (currently hard-coded to main). |
| docs/source/_static/version-redirect.js | Adds a JS-based redirect helper (currently not referenced/loaded). |
| docs/scripts/generate_versions_json.py | Generates versions.json and a root index.html redirect based on built version directories. |
| docs/scripts/build_versions.py | Adds a helper to filter/prune versions to keep a bounded set. |
| docs/requirements.txt | Removes sphinx-multiversion from the docs dependency set. |
| docs/Makefile | Adds a current-docs target for local/PR documentation builds. |
| .github/workflows/main.yml | Updates CI to build and publish versioned docs and to retain/prune older releases. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| .PHONY: current-docs | ||
| current-docs: | ||
| @rm -rf "$(BUILDDIR)/html" | ||
| @$(SPHINXBUILD) -W --keep-going "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) |
Comment on lines
+98
to
+108
| # Write root index.html redirect | ||
| index_path = html_dir / "index.html" | ||
| index_content = ( | ||
| "<!DOCTYPE html>\n" | ||
| "<html><head>\n" | ||
| f" <title>EmbodiChain Docs</title>\n" | ||
| f' <meta http-equiv="refresh" content="0; url=./{latest}/index.html">\n' | ||
| "</head></html>\n" | ||
| ) | ||
| index_path.write_text(index_content) | ||
| print(f"Generated {index_path} (redirects to ./{latest}/index.html)") |
Comment on lines
20
to
+21
| Then you can preview the documentation in your browser at `docs/build/html/index.html`. | ||
|
|
Comment on lines
+92
to
+95
| html_context = { | ||
| "github_user": "dexforce", | ||
| "github_repo": "EmbodiChain", | ||
| "github_version": "main", |
Comment on lines
+34
to
+41
| data.versions.forEach(function(v) { | ||
| var opt = document.createElement("option"); | ||
| opt.value = base + "/" + v.name + "/index.html"; | ||
| opt.textContent = v.name + (v.name === data.latest ? " (latest)" : ""); | ||
| if (path.indexOf("/" + v.name + "/") !== -1) { | ||
| opt.selected = true; | ||
| } | ||
| sel.appendChild(opt); |
Comment on lines
+4
to
+7
| <title>Redirecting to the latest EmbodiChain documentation</title> | ||
| <meta charset="utf-8"> | ||
| <meta http-equiv="refresh" content="0; url=./main/index.html"> | ||
| </head> |
Comment on lines
+1
to
+26
| /** | ||
| * Version redirect script for multi-version documentation. | ||
| * Redirects to the latest stable release version, or falls back to 'main'. | ||
| */ | ||
|
|
||
| (function() { | ||
| 'use strict'; | ||
|
|
||
| // Try to fetch versions.json (generated by generate_versions_json.py) | ||
| fetch('versions.json') | ||
| .then(response => { | ||
| if (!response.ok) { | ||
| throw new Error('versions.json not found'); | ||
| } | ||
| return response.json(); | ||
| }) | ||
| .then(data => { | ||
| // Get the latest version from the JSON | ||
| const latestVersion = data.latest || data.versions?.[0]?.name || 'main'; | ||
|
|
||
| const currentPath = window.location.pathname; | ||
|
|
||
| // If we're at root, redirect to latest version | ||
| if (currentPath === '/' || currentPath.endsWith('/index.html') || currentPath.endsWith('/')) { | ||
| window.location.href = latestVersion + '/'; | ||
| } |
| """Helper script for filtering versions to maintain buffer size.""" | ||
|
|
||
| import re | ||
| from pathlib import Path |
Comment on lines
+67
to
+69
| key: docs-output-${{ github.run_id }} | ||
| restore-keys: | | ||
| docs-output- |
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.
Description
This PR adds multi-version documentation support so docs can be built and served across versions with version-aware redirects and metadata.
Summary of changes:
Motivation and context:
Dependencies:
Fixes # (issue)
Type of change
Screenshots
N/A (build/tooling/docs infra changes only)
Checklist
black .command to format the code base. (blackexecutable is not available in the current environment)