Re: [PATCH v2] docs: sphinx-pre-install: warn about unsupported Docutils versions

[Akira Yokosawa]

Hi,

On Mon, 14 Sep 2026 19:35:40 +0900, Masaharu Noguchi wrote:
> 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 a Docutils its LaTeX builder cannot cope with. 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
> 
> The 9.0.4 row needs no help from a distribution: 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.  Fedora 44 reaches the same
> state from the other direction, shipping Sphinx 8.2.3 -- which declares
> "docutils>=0.20,<0.22" -- patched to accept "<0.23".  Upstream ships this
> sort of work in a new minor rather than backporting it -- the Docutils
> 0.22 support went out as 9.0.0 after a backport to 8.2.x was asked for and
> declined [2] -- so neither 8.2.x nor 9.0.x will grow the #3099 fix in a
> point release.
> 
> Check for it, since sphinx-pre-install exists precisely to catch a
> documentation build environment that will not work.  Ask the interpreter
> behind sphinx-build for its Docutils version -- a venv and the system
> install can differ -- and warn when Sphinx is older than 9.1.0 while
> Docutils is 0.22 or newer, naming both ways out -- a newer Sphinx or an
> older Docutils.  Only warn: the build is left to proceed, and htmldocs is
> unaffected.  The bound Sphinx declares is no use here: it is either what
> the distribution changed, or, for 9.0.x, wider than what the LaTeX builder
> delivers.
> 

As this is expected to be resolved in Fedora 45, I didn't see much
point in adding this warning.  I now see Ubuntu 24.04 LTS has the
problematic pair of Sphinx and docutils ...  So it might be worth
to have. 

That said, with your approach, under a build env with a problematic
pair, this is what you'd see in "make htmldocs":

$ make htmldocs
Warning: Sphinx 8.2.3 with Docutils 0.22.4 produces
   broken LaTeX for the large literal blocks in this
   documentation: pdfdocs will fail. Building them needs
   Sphinx 9.1.0 or later, or Docutils below 0.22.
   HTML builds are unaffected.
[...]

I think this can annoy people who only care HTML docs.

Why not do this check after the PDF doc builds have actually failed.

That is what sphinx-build-wrapper is doing with LatexFontChecker().check()
(see line 557 of tools/docs/sphinx-build-wrapper), which is to
show the way to work around PDF build errors caused by "variable font"
flavor of Noto CJK fonts [3].  (Fedora and openSUSE have started to
deploy such fonts in 2024.)

[3]: https://bugzilla.redhat.com/show_bug.cgi?id=2271559

Regards, Akira

> [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>
> ---

[...]