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

[Masaharu Noguchi]

Hi Mauro,

Thank you for looking at this.  Both directions you suggest are ones I went
down first; here is what I measured.

On Mon, 14 Sep 2026 07:42:06 +0200, Mauro Carvalho Chehab wrote:
> 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.

main_memory is counted in words rather than bytes, so that 6000000 is not 6
GB -- but raising it does not help either.  Fedora 44, the broken pairing
held fixed, varying only extra_mem_top/extra_mem_bot:

	             core-api             admin-guide
	----------------------------------------------------------------
	stock        FAILS 26x Dim 1194p  FAILS capacity 13p
	+60M words   FAILS 26x Dim 1194p  FAILS 40x Dim 2886p, no capacity

core-api does not move at all, and admin-guide, once TeX has all the memory
it asks for, fails on "Dimension too large" instead: the memory was masking
those boxes, not causing them.  Neither produces a PDF.

> This is also another parameter that may require adjustments.
> If I'm not mistaken, this is related to the maximum level depth
> on titles.

That one is maxlistdepth, which Documentation/conf.py already sets to 10.
\fb@put@frame is framed.sty's frame placement macro, and what it reports is
a box past TeX's maximum dimension, 16383.99998pt, which no setting raises.
Bisecting a single block under the kernel's LaTeX settings, 1450 lines
builds and 1500 does not, at stock memory and at ten times it;
memory-barriers.txt is 3016 lines.  I wrote an override for \fb@put@frame
too, and dropped it: the same content passes unframed under an older
Docutils.

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

This is what I should have shown in v1.  Same container, same TeX Live, same
unmodified texmf.cnf, same tree; only the two Python packages differ:

	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 is a plain "pip install sphinx==9.0.4": 9.0.x declares
"docutils>=0.20,<0.23" upstream, so pip resolves Docutils to 0.22.4 by
itself, with no distribution involved.

You are right that it takes a combination, and I will say that plainly
rather than pointing at one package.

> I don't mind having a warning

One thing needs fixing regardless: Akira pointed out that the fix for this,
sphinx-doc/sphinx#3099, landed in Sphinx 9.1.0 rather than 9.0.0, so v1's
constant skips the 9.0.4 row above.  I think that calls for a v2, with the
constant fixed and the commit message reworded as described.

Thanks,
Masaharu