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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

On Sun, 13 Sep 2026 12:13:23 +0900
Masaharu Noguchi <nogunix@gmail.com> 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.  admin-guide runs out of TeX main memory 13 pages in:
> 
>   ! TeX capacity exceeded, sorry [main memory size=6000000].
>   \sphinxafterbreak ->\copy \sphinxcontinuationbox

With some distros/versions, it is needed to change a config file
to use more memory. On Fedora, the limit is here:

	$ grep main_memory /etc/texlive/web2c/texmf.cnf
	% main_memory is relevant only to initex, extra_mem_* only to non-ini.
	% Thus, have to redump the .fmt file after changing main_memory; to add
	main_memory = 6000000 % words of inimemory available; also applies to inimf&mp

I haven't tested but it seems that there's a way to adjust it when
calling LaTeX:

	https://tex.stackexchange.com/questions/7953/how-to-expand-texs-main-memory-size-pgfplots-memory-overload

If so, maybe a more interesting patch would be to adjust pdf generaion
to use a more reasonable memory limit, as 6GB sounds too little.

> while arch, core-api and translations stop on
> 
>   ! Dimension too large.
>   \fb@put@frame ...p \ifdim \dimen@ >\ht \@tempboxa
>   \end{sphinxVerbatim}

This is also another parameter that may require adjustments.
If I'm not mistaken, this is related to the maximum level depth
on titles. I had to change some limit from 7 to 9 on some distros
in the past. I don't remember exactly where.

On both cases, I don't think you can blame docutils or sphinx
version: those are distro-specific configuration parameters.

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

Upstream policy AFAICT is to not backport anything: once they release
a new major or minor, they stop maintaining the previous versions.

> 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.0.0 while Docutils is 0.22 or newer.  Only warn: the build is left to
> proceed, and htmldocs is unaffected.

I don't mind having a warning, but I don't think you can blame
docutils or Sphinx versions on both cases, as the error is related
to LaTeX. It sounds to be this is actually a combination of those
three packages plus some distro-specific latex cfg settings on
some of the shipped files.

Thanks,
Mauro