Repository navigation
Documentation doesn't generate with docutils >= 0.22 #139257
Description
Documentation
The html doc is not building with the new docutils >= 0.22. It's not a problem yet, because the current Sphinx used (sphinx~=8.2.0) doesn't install the latest one, but it's something that should be fixed for the future.
The problem can be reproduced:
$ cd Doc
$ python3 -m venv env
$ source env/bin/activate
$ pip install -r requirements.txt
$ pip install -U docutils
$ sphinx-build --pdb -b html . build/html
[...]
File "env/lib64/python3.13/site-packages/docutils/parsers/rst/states.py", line 1494, in parse_enumerator
ordinal = int(self.enum.converters[sequence](text))
TypeError: int() argument must be a string, a bytes-like object or a real number, not 'NoneType'
The actual problem is directly related to this line in docutils, done as part as this commit.
They wrap the converters with int so the monkey patch done in pyspecific.py doesn't work anymore.
# monkey-patch reST parser to disable alphabetic and roman enumerated lists
from docutils.parsers.rst.states import Body
Body.enum.converters['loweralpha'] = \
Body.enum.converters['upperalpha'] = \
Body.enum.converters['lowerroman'] = \
Body.enum.converters['upperroman'] = lambda x: None
Activity
Update python310 to version 3.10.18 / rev 67 via SR 1308252
Update python314 to version 3.14.0~rc3 / rev 26 via SR 1308302
Update python311 to version 3.11.13 / rev 59 via SR 1308253
Update python312 to version 3.12.11 / rev 38 via SR 1308661
stefanor commentedon Oct 13, 2025
Coming here from Debian which is hitting the same issue:
I would expect all Linux distributions to run into this. We build self-contained systems. This typically requires things to work with the latest versions of each other. We can hold something at an older version for a while while we figure out an issue, but pinning anything to an ancient version is not possible.
pythongh-139257: docutils 0.22 support
pythongh-139257: docutils 0.22 support
pythongh-139257: docutils 0.22 support
picnixz commentedon Oct 13, 2025
I see. @AA-Turner The fix on our side is not really hard and I think this would help getting the latest python on mainstream distros. Would you be willing to reconsider your position here?
gpshead commentedon Oct 13, 2025
How is anyone maintaining documentation supposed to know what needs escaping? These escapes are unnatural.
What checks do we have in place that prevent docs from being checked in that conflict with unsupported-by-us future versions of docutils? Unless we have linting and CI checks that make these very-awkward escaping rules discoverable in our docs maintenance I expect such a PR will be temporary at best and regress in the future.
That doesn't mean we should not simply apply the PR for practical purposes - but nobody can expect our doc builds to stay working for the long term on arbitrary not-what-we-use docutils version without a CI test matrix in place.
stefanor commentedon Oct 14, 2025
My PR #139257 removed the monkeypatch, because things were escaped, but it could instead raise an exception, as I proposed on it.
From my PoV, I don't think that's something you really need to worry about. If things break loudly (like this) people will come and fix them. If they break silently, maybe you won't hear for a while, but you'll have the same silence problem when you make the docutils upgrade yourself.
Python could, of course, have a CI job that builds the docs with upstream unpinned versions of things, that'd probably be nice. But I'm not a Python Core developer at this point, so I'm not going to propose that you take on the burden of maintaining that.
befeleme commentedon Nov 24, 2025
Late to the party, but coming from Fedora with the same issue - also confirming that pinning is not really an option for us. I managed to fix or backport the fixes to all packages broken with docutils 0.22 in Fedora, the ecosystem seems to be pretty prepared for it. For me, it's just the Python docs left.
pythonGH-139257 Use an explicitly named link
picnixz commentedon Nov 29, 2025
Since this issue has been addressed in #121970, I'm going to close this it. We went for an alternative change that doesn't monkeypatch docutils.
picnixz commentedon Nov 29, 2025
We also fixed this in #142057.