Re: [PATCH v3] docs: report Sphinx/Docutils pairs that break PDF builds

[Jonathan Corbet]

Masaharu Noguchi <nogunix@xxxxxxxxx> writes:

> Sphinx declares the range of Docutils versions it supports, but that range
> does not always describe what its LaTeX builder can take: a distribution
> may relax the upper bound to ship a newer Docutils, and Sphinx 9.0.x
> declares support for Docutils 0.22 by itself.  Either way the pair
> installs happily and htmldocs builds without a complaint, so nothing looks
> wrong until pdfdocs is run, where four of the books fail:
>
>   ! Dimension too large.
>   \fb@put@frame ...p \ifdim \dimen@ >\ht \@tempboxa
>   l.86321 \end{sphinxVerbatim}
>
> That is arch, core-api and translations; admin-guide runs out of TeX
> memory first and stops 13 pages in, and fails on the same boxes once given
> more.  Each of the four includes a large literal file whole; the one in
> core-api, memory-barriers.txt, is 3016 lines.  Docutils 0.22 is what puts
> those blocks into sphinxVerbatim rather than sphinxalltt, and
> sphinxVerbatim is framed, so they hit the size limit of
> sphinx-doc/sphinx#3099 [1] -- open since 2016 and fixed only in Sphinx
> 9.1.0.  None of the three is at fault on its own: it takes the Docutils
> version, the Sphinx version and blocks this large.
>
> Keeping everything else fixed -- one Debian 13 container, one TeX Live, an
> unmodified texmf.cnf, one kernel tree -- and varying only the two Python
> packages:
>
>   sphinx   docutils   core-api   admin-guide
>   ------------------------------------------
>   8.2.3    0.21.2     ok         ok
>   8.2.3    0.22.4     FAILS      FAILS
>   9.0.4    0.22.4     FAILS      FAILS
>   9.1.0    0.22.4     ok         ok
>
> Two distributions ship the failing pair today.  Ubuntu 26.04 LTS has
> Sphinx 8.2.3 with Docutils 0.22.4 and no upper bound at all in the
> python3-sphinx dependency, and Fedora 44 reaches the same pair from the
> other side: it patches the "docutils>=0.20,<0.22" that Sphinx 8.2.3
> declares so that it accepts "<0.23".  Both fail identically here.  The
> 9.0.4 row needs no distribution's help: 9.0.0 through 9.0.4 declare
> "docutils>=0.20,<0.23" themselves, so a plain "pip install sphinx==9.0.4"
> resolves Docutils to 0.22.4.  Upstream ships this sort of work in a new
> minor rather than backporting it [2], so neither 8.2.x nor 9.0.x will grow
> the #3099 fix in a point release.
>
> Report it where it is useful: once pdfdocs has actually failed, next to
> the error, in the same place LatexFontChecker already explains the CJK
> variable font failures.  Ask the interpreter behind sphinx-build for both
> versions -- a venv and the system install can differ -- and name the two
> ways out.  htmldocs never runs this and stays silent, which matters
> because most people who build the documentation never build a PDF.
>
> [1]: https://github.com/sphinx-doc/sphinx/issues/3099
> [2]: https://github.com/orgs/sphinx-doc/discussions/14055
>
> Signed-off-by: Masaharu Noguchi <nogunix@xxxxxxxxx>

I'm sorry, but no.  This is a great deal of complexity to catch a
single, hard-coded mismatch that will soon disappear into history.
Instead:

- File bugs with the distributors involved

- If you *really* wanted to test for this sort of thing, it could be
  much more simply done with a Sphinx extension.  Trying to parse
  shebangs and such seems ... inelegant.

Finally, this has the look of LLM-generated stuff; if so, you need to be
adding Assisted-by tags to your patches.

Thanks,

jon