.. _docs-system-tooling-version-matrix:


######################################################################
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
**********************************************************************

.. _docs-system-tooling-version-matrix-baseline:

.. list-table::
   :header-rows: 1
   :widths: 28 18 54

   * - 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
       :ref:`docs-system-tooling-version-matrix-theme`.

Built-in extensions --- mandatory
======================================================================

.. _docs-system-tooling-version-matrix-builtin-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
======================================================================

.. _docs-system-tooling-version-matrix-builtin-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
======================================================================

.. _docs-system-tooling-version-matrix-external-mandatory:

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

.. list-table::
   :header-rows: 1
   :widths: 40 15 45

   * - 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
======================================================================

.. _docs-system-tooling-version-matrix-external-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
**********************************************************************

.. _docs-system-tooling-version-matrix-theme:

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
:ref:`docs-system-reference-repo-registry`.


**********************************************************************
Per-Repo Overrides
**********************************************************************

.. _docs-system-tooling-version-matrix-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.

.. code-block:: yaml

   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
**********************************************************************

.. _docs-system-tooling-version-matrix-deprecated:

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.

.. list-table::
   :header-rows: 1
   :widths: 30 30 40

   * - 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
**********************************************************************

.. _docs-system-tooling-version-matrix-upgrade:

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

1. **Edit** ``source/_data/versions.yml`` with the proposed new pin.
   Update any affected ``rationale`` text. Mention the bump in
   ``CHANGELOG.rst``.
2. **Sync** ``~/.local/share/docs-system/versions.yml``:

   .. code-block:: bash

      cp source/_data/versions.yml ~/.local/share/docs-system/

   (Phase 3 tooling will automate this; until then, do it by hand.)
3. **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.
4. **Rebuild the rendering container.** Rebuild
   ``sphinx-custom-image`` so the container matches the new pins.
5. **Rebuild every repo.** Run ``make html`` in each Tier 1 repo and
   the Tier 2 hub; catch any extension compatibility regressions.
6. **Audit overrides.** Read every entry in the ``overrides:`` block.
   Remove any whose reason no longer applies.
7. **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
**********************************************************************

.. _docs-system-tooling-version-matrix-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.