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

[Akira Yokosawa <akiyks@gmail.com>]

Hi,

On Sun, 13 Sep 2026 12:13:23 +0900, Masaharu Noguchi wrote:
> Sphinx declares the range of Docutils versions it supports, but a
> distribution can relax that upper bound when it wants to ship a newer
> Docutils.  The pair then installs happily, and htmldocs builds without
> a complaint, so nothing looks wrong until pdfdocs is run.
> 
> Fedora 44 ships such a pair: Sphinx 8.2.3 (which declares
> "docutils>=0.20,<0.22") is patched to accept "<0.23" and is installed
> alongside Docutils 0.22.4.  make pdfdocs then fails to produce four of
> its books.

It sounds to me like a packaging issue in Fedora side.

I'd rather ask Fedora's Sphinx maintainer to backport the fix applied
in Sphinx 9.1.0 to their Sphinx 8.2.3.

>            admin-guide runs out of TeX main memory 13 pages in:
> 
>   ! TeX capacity exceeded, sorry [main memory size=6000000].
>   \sphinxafterbreak ->\copy \sphinxcontinuationbox
> 
> while arch, core-api and translations stop on
> 
>   ! Dimension too large.
>   \fb@put@frame ...p \ifdim \dimen@ >\ht \@tempboxa
>   \end{sphinxVerbatim}
> 
> Both come from the large literal blocks those books include whole --
> memory-barriers.txt, devices.txt, kernel-parameters.txt and
> arch/sparc/oradax/dax-hv-api.txt.  Keeping everything else fixed and
> varying only the two versions shows that neither component is at fault
> on its own:
> 
>   sphinx   docutils   core-api   admin-guide
>   ------------------------------------------
>   8.1.3    0.21.2     ok         ok
>   8.2.3    0.21.2     ok         ok
>   8.2.3    0.22.4     FAILS      FAILS
>   9.1.0    0.22.4     ok         ok
> 
> Sphinx gained Docutils 0.22 support in 9.0.0

This is not the case.  It was done in Sphinx 9.1.0.

>                                                and upstream decided not
> to backport it to 8.2.x [1], so this pair will stay broken rather than
> be fixed in a later 8.2 point release.
> 

As this is an transient issue, I don't see much point in bothering it
in a kernel documentation script.  Fedora 45 will come with Sphinx 9.1.0.

Regards, Akira

PS:

I was involved in testing the upstream fix.
  (https://github.com/sphinx-doc/sphinx/issues/3099)

[...]