Repository navigation
Description
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.changesintests/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 asnumber="1"onmath_blockmust not be rewritten. - Generate the
.sphinx9baselines 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
testingandrtdcaps from<9to<10. - Consider dropping Python 3.10, which reached end of life in October 2026. That would also remove the
.sphinx8.1fixture 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.styrequests 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 onmain. That code now usespathlib, 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