Skip to content

Support Sphinx 9: add it to CI and lift the <9 cap on the testing and docs extras #96

Open

Description

@mmcky

sphinx-exercise depends on sphinx>=6.1 with no upper bound, so installing it today gives users Sphinx 9: 9.2.0 on Python 3.13 and later, 9.1.1 on Python 3.11 and 3.12. The testing and rtd extras (sphinx>=6.1,<9), tox.ini and the CI matrix all stop at Sphinx 8, so nothing tests what users actually install.

Current state on Sphinx 9

The full suite at 599a08a was run against Sphinx 9.1.1 (Python 3.12) and Sphinx 9.2.0 (Python 3.13), with docutils 0.22.4, myst-nb 1.4.0 and sphinx-book-theme 1.4.0, which all resolve together. Both runs gave 55 passed and 62 failed, with identical results. None of the failures is a crash or a wrong result; all 62 are regression-fixture mismatches:

Failures Cause
34 No .sphinx9 baseline exists, so pytest-regressions writes one and fails. Of the 34 files it wrote, 22 are byte-identical to the .sphinx8 baselines, 11 XML files differ only in boolean serialisation (next row), and 1 is a real LaTeX change (see below).
28 Version-independent XML doctree baselines (22 in test_exercise and test_exercise_references, 6 in test_solution_references) differ only in boolean serialisation.

Boolean serialisation. docutils 0.22 writes boolean attribute values as 1 and 0 instead of True and False. Sphinx 9.0 is the first Sphinx release that allows docutils 0.22 (Sphinx 8.2.3 requires docutils>=0.20,<0.22). The change affects Sphinx's attributes as well as ours: across the 28 diffs, the only changed attributes are refwarn, refexplicit, hidden, and docutils' nowrap / no-wrap. docutils alone shows it: an element with hidden=False and refwarn=True prints as hidden="False" refwarn="True" under docutils 0.21.2 and as hidden="0" refwarn="1" under docutils 0.22.4.

LaTeX solution titles. Sphinx 9 removed the self.in_title check from LaTeXTranslator.visit_reference, so references inside titles are now written as links. In LaTeX output, "Solution to Exercise N" titles change from plain text to \hyperref[...]{\sphinxcrossref{...}}, which matches the HTML output, where the title is already a link. This needs a .sphinx9 LaTeX baseline but no code change.

Sphinx 9.1.1 and 9.2.0 produced identical baselines, so a single .sphinx9 suffix is enough.

The docs build (the rtd extra with Sphinx 9.2.0) succeeds with one warning, a link to syntax.md#solution-title-styling whose heading anchor is not generated. That is a docs content issue rather than a Sphinx 9 one.

Suggested changes

  • Normalise boolean serialisation in FileRegression.changes in tests/conftest.py, next to the existing Sphinx-version normalisations, so the version-independent baselines keep working. Limit it to the boolean attributes (refwarn, refexplicit, hidden, nowrap, no-wrap), because numeric attributes such as number="1" on math_block must not be rewritten.
  • Generate the .sphinx9 baselines deliberately and review them before committing. pytest-regressions writes a missing baseline as a side effect of a failing run, so baselines created incidentally in a local environment can be committed by accident. With the normalisation in place, only the LaTeX baseline should differ from .sphinx8.
  • Add Sphinx 9 to the CI matrix and tox.ini for Python 3.11 to 3.13. Sphinx 9 requires Python 3.11 or later and 9.2 requires 3.13 or later, so the 3.11 and 3.12 jobs will resolve 9.1.x, much as Python 3.10 resolves Sphinx 8.1.x today.
  • Change the testing and rtd caps from <9 to <10.
  • Consider dropping Python 3.10, which reached end of life in October 2026. That would also remove the .sphinx8.1 fixture special case, which exists only for Python 3.10.

Caveats

  • PDF output on Sphinx 9 could not be checked. With TeX Live 2026, Sphinx 9.1.1 and 9.2.0 LaTeX builds fail even for a project that does not use sphinx-exercise: sphinxlatextables.sty requests a rollback with \RequirePackage{array}[=v2.6], and LaTeX stops with "Requested version 'v2.6' for package 'array' is unknown". That is an upstream Sphinx problem; no existing report turned up in sphinx-doc/sphinx.
  • sphinx_exercise/post_transforms.py:198: Use "pathlib.Path" or "os.fspath" instead. #76 (a Sphinx 9 path-handling warning in post_transforms.py) looks already resolved on main. That code now uses pathlib, and _linked_wrong_targetlabel, which runs it, raises no path warning on Sphinx 9. It can probably be closed once Sphinx 9 is in CI.

Sphinx 9 also deprecates the app attributes that sphinx-exercise uses, for removal in Sphinx 11. That is tracked separately in #97.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions