#14680·sphinx

Docutils 1.0 development changes break native doctests and table widths

Author: DarloktCreated Sep 13, 2026Updated Sep 19, 2026
Labelstype:bugdocutils

Describe the bug

Hej, this is the last of the the CI failures on #14677. I noticed that two node representation changes in the Docutils 1.0 development version break Sphinx's handling of native reStructuredText doctests and table column widths.

Docutils now parses a native doctest as a literal_block with the classes code, pycon, and doctest, instead of as a doctest_block. Sphinx only recognizes the old node type when it assigns the highlighting language, collects automatic doctests, and moves an indented native doctest out of a block quote. The new node can therefore lack a language attribute, be skipped by the doctest builder, and remain inside a <blockquote> in HTML.

Docutils also represents proportional colwidth attributes as strings. Sphinx's text, LaTeX, and Texinfo writers perform integer arithmetic on these values, while autosummary still creates integer attributes that the Docutils development XML writer treats as strings. This produces errors in both directions at the Sphinx/Docutils boundary.

How to Reproduce

Run:

bash
uv sync
uv run --no-sync --with \
  'docutils @ git+https://repo.or.cz/docutils.git@335c924f838ac9180231cf2164f301cc6f6b4ca1#subdirectory=docutils' \
  pytest -q --tb=short \
  tests/test_builders/test_build_text.py::test_lineblock \
  tests/test_extensions/test_ext_doctest.py::test_highlight_language_default \
  tests/test_ext_autosummary/test_ext_autosummary.py::test_escaping

The run produces three failed tests and exit code 1:

  • the text writer failed while combining integer and string column width
  • the doctest highlighting test failed with KeyError: 'language'
  • the XML writer failed while handling autosummary's integer colwidth

The same three tests pass with the locked Docutils 0.22.3.

Environment Information

Platform:              linux; (Linux-7.0.0-31-generic-x86_64-with-glibc2.43)
Python version:        3.13.13 (main, Apr  7 2026, 20:49:46) [Clang 22.1.1 ])
Python implementation: CPython
Sphinx version:        9.1.1+/e44a40eb2
Docutils version:      1.0b1.dev
Jinja2 version:        3.1.6
Pygments version:      2.19.2

Sphinx extensions

python
['sphinx.ext.autosummary', 'sphinx.ext.doctest']

Additional context

The AI under #14673 already proposes changes to the same compatibility surfaces, but it misses the transform that moves indented native doctests out of block quotes.