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

[Mauro Carvalho Chehab]

On Tue, 15 Sep 2026 16:52:03 +0900
Akira Yokosawa <akiyks@xxxxxxxxx> wrote:

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

Fedora 44 EOL is still in at least 7 months from now (e.g. when Fedora
46 will be launched), so, it could still be worth.

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

Indeed it sounds a better approach on my eyes.

---

On a separate but related issue, has anyone tried to use rst2pdf
lately (https://github.com/rst2pdf/rst2pdf)?

It could be helpful to use an approach that won't require writing
first a LaTeX file. I remember I implemented some support for it
a long time ago. The patch back them is still on an old branch
here:

	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst2pdf-v3

If someone has the time, it could be worth trying to port it for
it to work with sphinx-build-wrapper and do some tests to check
if it is worth the efforts to fix existing bugs at the tool, if
any.

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



Thanks,
Mauro