Version Matrix

Single source of truth for the Python interpreter, Sphinx version, and extension set that every Documentation System repo runs against. Both local pyenv virtualenvs and the sphinx-custom-image rendering container derive their pins from this matrix.

Note

Authoritative file: source/_data/versions.yml (tracked in this repo).

The same file is synced to ~/.local/share/docs-system/versions.yml for consumption by global scripts. Until the Phase 3 sync tooling ships, the ~/.local/share copy is refreshed manually (cp source/_data/versions.yml ~/.local/share/docs-system/) whenever the tracked file changes.

Current Baseline

Component	Pin	Rationale
Python	`3.13.1`	Current stable major; aligns with extension support across the mandatory set and keeps us ahead of the forced-upgrade cycle.
Sphinx	`8.1.3`	Current major; required by the mandatory extension pins below.
Theme	per-repo	Not governed here. Each repo picks its own theme and records it in the notes column of the repo registry. See docs-system-tooling-version-matrix-theme.

Built-in extensions — mandatory

Required in every repo’s conf.py extensions list. Ship with Sphinx; no pip install needed.

sphinx.ext.intersphinx — cross-repo linking is core to the architecture.
sphinx.ext.todo — every repo has TODOs.
sphinx.ext.graphviz — fleet-wide availability of Graphviz diagrams.
sphinx.ext.viewcode — source viewing for any repo that documents code.
sphinx.ext.extlinks — URL-pattern shortcuts (:github:, :rfc:, etc.).

Built-in extensions — optional

Available everywhere; enabled per-repo when the behavior is wanted.

sphinx.ext.autosectionlabel — conflicts with the explicit label-prefix convention. Enable only if a repo explicitly wants auto-generated labels alongside the prefixed ones.

External extensions — mandatory

Pinned pip packages; installed into every repo’s virtualenv and the sphinx-custom-image rendering container.

Package	Pin	Rationale
`myst-parser`	`4.0.0`	Mandatory Markdown parser; replaces the deprecated `recommonmark`.
`sphinxcontrib-mermaid`	`1.0.0`	Inline Mermaid diagrams.
`sphinxcontrib-youtube`	`1.4.1`	Embedded video; replaces the legacy `sphinxcontrib.yt` fork.
`sphinx-copybutton`	`0.5.2`	Universal copy-to-clipboard button on code blocks.

External extensions — optional

Empty at baseline. Add entries to external_extensions.optional in versions.yml when a new extension becomes common enough to justify fleet-wide availability but not universal enough to be mandatory.

Theme Policy

Theme selection is intentionally left to each repo. Existing repos using sphinx_rtd_theme stay on it (migration has no payoff for already-working sites); new repos may choose any actively-maintained theme (furo is a reasonable default). The fleet-wide pin would force a migration that is not worth the churn, so the version matrix declares theme: per-repo and defers the choice.

Record the theme a repo uses in the notes column of Repository Registry.

Per-Repo Overrides

Per-repo exceptions live in the overrides: block of versions.yml, keyed by project slug. Every override carries a reason field explaining why the exception exists.

overrides:
  linux-docs:
    python: "3.12.7"
    reason: "extension X not yet 3.13-compatible; revisit 2026-07"
  ai-docs:
    external_extensions:
      mandatory:
        myst-parser: "3.0.0"
    reason: "..."

Overrides are reviewed at every baseline version bump. Stale overrides — those whose reason no longer applies — are removed in the same bump that resolves them.

Deprecated Packages

Packages listed here are no longer permitted in new repos, and are replaced in existing repos as part of Phase 2 normalization. Each deprecation carries its replacement and reason in versions.yml so conf.py audits can surface them automatically.

Deprecated	Replacement	Reason
`recommonmark`	`myst-parser`	Unmaintained upstream; `myst-parser` is the community standard and supports the vast majority of `recommonmark` input unchanged.
`sphinxcontrib.yt`	`sphinxcontrib-youtube`	Legacy namespace fork; `sphinxcontrib-youtube` is the maintained line.
`sphinxcontrib-inlinesyntaxhighlight`	(none — remove)	Abandoned upstream (last release 2014); imports `BaseTranslator` from `sphinx.writers.html` which was removed in Sphinx 8. The `:code:` role it provided was not used anywhere in the fleet. Remove from any repo that loads it.

Upgrade Workflow

Bumping any pin — Python, Sphinx, or any mandatory extension — follows a fixed sequence so local envs and the rendering container cannot silently drift.

Edit source/_data/versions.yml with the proposed new pin. Update any affected rationale text. Mention the bump in CHANGELOG.rst.
Sync ~/.local/share/docs-system/versions.yml:
```
cp source/_data/versions.yml ~/.local/share/docs-system/
```
(Phase 3 tooling will automate this; until then, do it by hand.)
Rebuild local envs. For every repo in the registry, run the forthcoming docs-env.sh sync against the repo’s pyenv virtualenv. Until that script exists, the manual equivalent is pip install -r requirements-docs.txt with the refreshed pins.
Rebuild the rendering container. Rebuild sphinx-custom-image so the container matches the new pins.
Rebuild every repo. Run make html in each Tier 1 repo and the Tier 2 hub; catch any extension compatibility regressions.
Audit overrides. Read every entry in the overrides: block. Remove any whose reason no longer applies.
Commit. One commit touching versions.yml, the sync copy (if tracked), and the affected CHANGELOG.rst entries. Commit message: tooling: bump <component> to <version>.

Ownership

Version bumps are a deliberate act, not an automated one. Claude Code may propose a bump via PR; a human approves and merges. Each bump triggers the seven-step rebuild workflow above, so versions.yml changes carry real cost and are batched accordingly.