Feat/versioned docs preview#6
Merged
Merged
Conversation
Adds env-gated multi-version build support to the umbrella docs.
Production single-version CI is unchanged — every change here is a
no-op until DOCS_MULTIVERSION=1 is set, which only the new Makefile
targets do.
What's wired:
conf.py
- DOCS_MULTIVERSION env switches the PyData theme into "show
version-switcher" mode and appends `version-switcher` to
navbar_end.
- DOCS_VERSION env (default "latest") tells the theme which
switcher.json row is the current page.
- DOCS_DEPLOY_BASE env (default https://microrobotica.org)
sets the public root; overridden to http://localhost:8000
by the Makefile preview targets.
- MULTIPROJECT_PATH_<UPPER_PROJECT> env can point a project at
a git worktree of a specific tag/branch rather than the live
submodule pointer — the Makefile uses this per-version.
- check_switcher=False silences the theme's startup warning if
the JSON URL isn't reachable at build time.
- Adds the active sub-project's _static/ (absolute path) to
html_static_path so a project's switcher.json actually lands
in the build output (the umbrella's _static/ alone doesn't
cover subproject _static/).
Makefile
- MADDENING_VERSIONS / MIME_VERSIONS / MICROROBOTICA_VERSIONS
lists declare which (label : git-ref) tuples to build.
- _build-version recipe: prunes stale worktrees, fetches the
submodule, creates a fresh detached worktree under
/tmp/msf-docs-worktree-<project>-<label>, runs sphinx-build
against it, validates that the ref still has docs/index.md.
- {maddening,mime,microrobotica}-versions targets expand the
version lists into per-version builds.
- all-versions builds everything; preview-versions adds an
http.server on :8000.
- preview-local MADDENING_LOCAL=... builds the "latest" tier
from a local working copy for fast iteration without
committing.
- clean-worktrees removes the /tmp dirs.
- microrobotica build is doxygen-optional so the preview
works without a doxygen install.
developer_guide/multiversion_preview.md
- Workflow doc: quick start, knobs reference, troubleshooting,
what's still on the rollout list before this can ship.
Verified locally:
./_build/html/maddening/ ← origin/feat/v0.2 (latest)
./_build/html/maddening/v0.1/ ← v0.1.0 tag
./_build/html/maddening/v0.2-dev/ ← origin/feat/v0.2 (preview alias)
./_build/html/maddening/_static/switcher.json ← canonical version list
./_build/html/mime/ ← origin/main
./_build/html/index.html ← microrobotica root
All versions reference /maddening/_static/switcher.json (root-relative),
so older releases pick up newer dropdown entries automatically when
the canonical JSON is updated by the next "latest" build.
Branch only — NOT merged to main, NOT deployed. Once v0.2 MADDENING
ships, the CI workflow change to swap `make all` → `make all-versions`
is the final cut.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Step 7 of the MADDENING v0.2.0 release checklist. Bumps docs/projects/maddening from the pre-v0.2 commit 5cf74c9 to the v0.2.0 tag (ff59eb5) so the umbrella docs build against the released MADDENING source. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…URLs - Makefile: SPHINXBUILD auto-detects the sibling shared venv so the build runs without activating it first; add a _check-sphinx guard with an actionable message instead of the cryptic "env: sphinx-build: No such file or directory"; MADDENING_VERSIONS now lists the released v0.2 (v0.1:v0.1.0 v0.2:v0.2.0 latest:origin/main); preview-local derives its version set from MADDENING_VERSIONS so the list can't drift. - conf.py: drop sphinx-sitemap on non-latest builds. Versioned pages already canonicalise to the latest URL (html_baseurl is versionless), so only the canonical build needs a sitemap — no more redundant per-version sitemap.xml files. - _static/switcher.json: single-entry version switcher for the root MICROROBOTICA project. - multiversion_preview.md: refreshed for the v0.2.0 release; new "Canonical URLs and the sitemap" section documenting the design. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The pydata theme's switcher button is sized for short tokens and clips names like "v0.2 (stable)". Add a min-width + nowrap rule for the button and its dropdown menu. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Switch the docs workflow from `make all` (single-version) to `make all-versions`, which builds every version in the Makefile's *_VERSIONS lists into /<project>/<version>/ subdirs. Set DOCS_DEPLOY_BASE=https://microrobotica.org so the version targets don't fall back to their localhost preview default. This is the last step of the versioned-docs rollout — it takes the PyData version switcher live on microrobotica.org. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
NicholasEhsanRoy
added a commit
that referenced
this pull request
May 30, 2026
Consolidates the multi-version docs scaffolding back into main now that v0.2.1 is live. The 'feat/versioned-docs-preview' branch served as the preview deploy source during the v0.2 cycle (PR #6 brought the bulk of the multi-version Makefile + conf.py switcher + docs.yml into main); this merge folds in the trailing commit that added MADDENING v0.2.1 to MADDENING_VERSIONS and bumped the submodule pointer to the v0.2.1 tag. After this lands, future docs deploys trigger automatically on push to main (no more manual workflow_dispatch on a feature branch, no more github-pages branch-protection carve-out). Adding a new MADDENING release becomes: bump the docs/projects/maddening submodule + add one entry to MADDENING_VERSIONS in docs/Makefile, on main. The 'feat/versioned-docs-preview' branch is now redundant; safe to delete after this merge.
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
1 participant
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.
No description provided.