Skip to content

README.md

Latest commit

 

History

History
196 lines (141 loc) · 6.88 KB

README.md

File metadata and controls

196 lines (141 loc) · 6.88 KB
Raw

Docs Build and Versioning

This folder contains the Sphinx documentation source and build tooling for local development and GitHub Pages publishing.

Contents

Prerequisites

  • Python environment with docs dependencies installed:
    • pip install --require-hashes --no-deps -r requirements-docs.lock
    • or (less strict) pip install -r requirements-docs.txt
  • Install the Enchant C library (required by sphinxcontrib-spelling):
    • macOS (Homebrew): brew install enchant
    • Windows (Chocolatey): choco install enchant
  • Run commands from the repo root with make -C docs ..., or from this folder with make ....

Make Targets

The docs/Makefile supports these explicit targets:

  • make help
    • Shows Sphinx make-mode help and all supported builder targets.
  • make html
    • Standard single-version HTML build into docs/build/html.
  • make spelling
    • Runs the spelling builder and fails if any misspelled words are found (scripts/ci/docs_spelling_check.sh).
  • make md
    • Builds Markdown output to docs/build/markdown and copies images/static assets.
  • make html-multiversion
    • Builds versioned docs without sphinx-multiversion using scripts/build_versioned_docs.sh.
  • make html-multiversion-preview
    • Same as above, plus the current git branch as local-branch-preview.

Catch-all behavior is enabled:

  • Any unknown target is forwarded to sphinx-build -M.
  • Example: make clean, make linkcheck, make dirhtml.

Multiversion Implementation (No sphinx-multiversion)

Versioned docs are generated by:

  • docs/scripts/build_versioned_docs.sh (entrypoint)
  • docs/scripts/build_versioned_docs.py (orchestrator)
  • docs/scripts/select_versions.py (version selection rules)

What Gets Built

  • main branch is always built and published as current.
  • Selected release tags are built from git tags.
  • Docs IA cutover at v0.21.0:
    • current and tags >= v0.21.0 use main's docs/conf.py with that ref's docs/source (sphinx-immaterial / section-folder IA).
    • Tags <= v0.20.x use v0.20.0's docs/conf.py (RTD / flat layout) with each tag's own docs/source.
  • local-branch-preview (optional) uses the current branch's own conf + source (pre-merge validation).
  • Output layout:
    • docs/build/html/current/index.html
    • docs/build/html/vX.Y.Z/index.html
    • docs/build/html/versions.json
    • docs/build/html/index.html (redirects to current/index.html)

Version Selection Rules

scripts/select_versions.py applies these rules:

  1. Identify the highest major version present in tags.
  2. For major 0, include the latest patch release for every minor from the current minor down to 0.12 (inclusive).
  3. For other majors, include the latest patch release for the last 5 minor series in that major.
  4. Include the latest available release for each of the last 3 majors.
  5. De-duplicate and sort descending (newest first).

Example ordering:

  • current
  • v0.16.0
  • v0.15.5
  • v0.14.0
  • v0.13.0
  • v0.12.1
  • … through v0.12.x when older minors exist

How the Version Dropdown Works

  • scripts/build_versioned_docs.py writes a superset versions.json with:
    • mike / sphinx-immaterial fields: version, title, aliases
    • legacy RTD fields: name, display_version, url, status, is_latest, release_date
  • RTD-era refs load the manifest at build time via DOCS_VERSIONS_FILE into versions.html.
  • Immaterial refs enable version_dropdown and fetch the parent ../versions.json over HTTP (version_json in conf.py).
  • Use a local HTTP server to test the immaterial switcher (see below).

Preview builds

make -C docs html-multiversion-preview
  • Still publishes current from main.
  • Also builds the current git branch once as local-branch-preview (skipped if you are on main or detached HEAD).
  • To review a feature branch before merge, check it out, run preview, then select local-branch-preview in the version menu.
  • Preview builds from the working tree (uncommitted conf/theme/source edits are included).

Purge and Rebuild Behavior

Each versioned build is clean:

  • docs/build/html is removed before rebuilding.
  • Temporary git worktrees under docs/build/.worktrees are removed after build.
  • git worktree prune runs at the end.

This ensures old/stale version folders are purged from the publish artifact.

Local Build and Testing

Use this command order during docs development:

  1. Quick content/format validation while iterating:
make -C docs html
  1. Always run spelling before finalizing:
make -C docs spelling
  1. If your change could affect versioned output or version switcher behavior:
make -C docs html-multiversion
  1. If you need to preview the current branch against main / release tags:
make -C docs html-multiversion-preview

Practical rule of thumb:

  • Doc text/layout change only: html + spelling
  • Versioning/switcher/build-script change: html + spelling + html-multiversion
  • Branch theme/IA preview: html-multiversion-preview, then select local-branch-preview

Open docs

  • Direct file open:
    • docs/build/html/index.html
  • Recommended local server (more browser-consistent):
cd docs/build/html
python3 -m http.server 8000

Then open http://localhost:8000/current/index.html to exercise the version dropdown.

Note: make html builds a single-version tree without a parent-level versions.json; use html-multiversion to test version switching.

GitHub Pages Deployment

The workflow is in .github/workflows/main-docs.yml.

On push to main or release tags:

  1. Checkout full history and tags.
  2. Install docs dependencies.
  3. Run bash docs/scripts/build_versioned_docs.sh.
  4. Upload docs/build/html as Pages artifact.
  5. Deploy with GitHub Pages actions.

The deployed root redirects to current/index.html. Build output also includes:

  • sitemap.xml for search-engine discovery.
  • robots.txt referencing the sitemap.
  • Canonical URL metadata on pages, based on html_baseurl in docs/conf.py.

Notes and Troubleshooting

  • If version links look wrong, inspect docs/build/html/versions.json.
  • If tags seem missing, verify local git tags are fetched:
    • git fetch --tags
  • If local browser shows folder listing, use the explicit index.html URLs or run a local HTTP server.