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

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

[Masaharu Noguchi]

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

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

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.

Note that the bound Sphinx itself declares is of no use here, as that
is the very thing the distribution has changed.

[1]: https://github.com/orgs/sphinx-doc/discussions/14055

Signed-off-by: Masaharu Noguchi <nogunix@gmail.com>
---
Verified on Debian 13 over six Sphinx/Docutils combinations: the warning
appears for 8.2.3 with 0.22.4 and for nothing else, including the
boundaries at Sphinx 9.0.0 and Docutils 0.21.2.  Also checked on the
Fedora 44 host, where it fires as it should, and in a venv built from
Documentation/sphinx/requirements.txt, which resolves to Sphinx 9.1.0
and stays quiet.  make htmldocs and make pdfdocs are otherwise
untouched; the warning does not change the exit status.

This lands in the same area as Chen Miao's "docs: sphinx-pre-install:
improve dependency checks" series [1], which adds a GNU Make version
check alongside the existing Sphinx one.  It applies cleanly to mainline
today, but I am happy to rebase if that series goes in first.

[1]: https://lore.kernel.org/linux-doc/20260814214419.49925-1-chenmiao.ku@gmail.com/
---
 tools/docs/sphinx-pre-install | 69 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
index 965c9b093a41..d22287451e9b 100755
--- a/tools/docs/sphinx-pre-install
+++ b/tools/docs/sphinx-pre-install
@@ -41,6 +41,13 @@ from kdoc.python_version import PythonVersion
 RECOMMENDED_VERSION = PythonVersion("3.4.3").version
 MIN_PYTHON_VERSION = PythonVersion("3.7").version
 
+# Sphinx only learned to cope with Docutils 0.22 on its 9.0.0 release, and
+# upstream chose not to backport that to the 8.2.x series:
+#     https://github.com/orgs/sphinx-doc/discussions/14055
+# So the pair below is broken for good, not just until the next point release.
+MIN_DOCUTILS_SPHINX = PythonVersion("9.0.0").version
+DOCUTILS_BREAKS_AT = PythonVersion("0.22").version
+
 
 class DepManager:
     """
@@ -490,10 +497,72 @@ class MissingCheckers(AncillaryMethods):
             self.need_sphinx = 1
             return
 
+        self.check_docutils(sphinx)
+
         # On version check mode, just assume Sphinx has all mandatory deps
         if self.version_check and self.cur_version >= RECOMMENDED_VERSION:
             sys.exit(0)
 
+    def get_docutils_version(self, cmd):
+        """
+        Get the Docutils version a sphinx-build command would use.
+
+        Docutils is a Python module rather than a program, so it has to be
+        asked of the very interpreter that runs sphinx-build: a venv and the
+        system install can hold different versions. Take it from the script's
+        shebang, falling back to the interpreter running this script.
+        """
+        python = sys.executable
+
+        try:
+            with open(cmd, "r", encoding="utf-8") as f:
+                match = re.match(r"^#!\s*(\S+)", f.readline())
+                if match:
+                    python = match.group(1)
+        except (OSError, UnicodeDecodeError):
+            pass
+
+        try:
+            result = self.run(
+                [python, "-c", "import docutils; print(docutils.__version__)"],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+        except (OSError, subprocess.CalledProcessError):
+            return None
+
+        match = re.match(r"^\s*([0-9]+(?:\.[0-9]+)*)", result.stdout)
+        if not match:
+            return None
+
+        return PythonVersion.parse_version(match.group(1))
+
+    def check_docutils(self, sphinx):
+        """
+        Warn when Sphinx is paired with a Docutils it cannot handle.
+
+        Sphinx declares the Docutils range it supports, but distributions
+        sometimes relax that upper bound to ship a newer Docutils. The pair
+        still builds HTML, so nothing looks wrong until pdfdocs is run and
+        the LaTeX output turns out to be broken.
+        """
+        if not self.cur_version or self.cur_version >= MIN_DOCUTILS_SPHINX:
+            return
+
+        docutils_version = self.get_docutils_version(sphinx)
+        if not docutils_version or docutils_version < DOCUTILS_BREAKS_AT:
+            return
+
+        curver = PythonVersion.ver_str(self.cur_version)
+        docver = PythonVersion.ver_str(docutils_version)
+        minver = PythonVersion.ver_str(MIN_DOCUTILS_SPHINX)
+
+        print(f"WARNING: Sphinx {curver} does not support Docutils {docver}.")
+        print(f"         Docutils 0.22 and above need Sphinx {minver} or later.")
+        print("         PDF builds are known to produce broken LaTeX with this")
+        print("         combination, even though HTML builds fine.")
+
     def catcheck(self, filename):
         """
         Reads a file if it exists, returning as string.

---
base-commit: 5225b8eec4c9bb21aecff6295fab6346a3c3738e
change-id: 20260913-docs-sphinx-pre-install-docutils-7f14a21004a1

Best regards,
-- 
Masaharu Noguchi <nogunix@gmail.com>

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

[Akira Yokosawa]

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)

[...]

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

[Mauro Carvalho Chehab]

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

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

[Masaharu Noguchi]

Hi Akira,

Thank you for the review, and for the pointer to #3099.

On Mon, 14 Sep 2026 13:56:16 +0900, Akira Yokosawa wrote:
>> Sphinx gained Docutils 0.22 support in 9.0.0
>
> This is not the case.  It was done in Sphinx 9.1.0.

You are right about what matters here.  9.0.0 was announced as the release
with Docutils 0.22 support, but the LaTeX size limit that actually breaks
these builds is #3099, which was not fixed until 9.1.0 -- so the boundary
has to be 9.1.0, and v1's check skips the whole 9.0.x series.  I have since
built those, and they fail:

	sphinx   docutils   core-api   admin-guide
	------------------------------------------
	8.2.3    0.22.4     FAILS      FAILS
	9.0.0    0.22.4     FAILS      FAILS
	9.0.4    0.22.4     FAILS      FAILS
	9.1.0    0.22.4     ok         ok

Worth noting that the 9.0.x rows are not distro-patched: 9.0.0 through 9.0.4
declare "docutils>=0.20,<0.23" themselves, so a plain "pip install
sphinx==9.0.4" pulls Docutils 0.22.4 on its own.  So the pairing is reachable
without any distribution relaxing anything.

> Fedora 45 will come with Sphinx 9.1.0.

I tested that pairing before replying, and you are right: Sphinx 9.1.0 with
Docutils 0.23, which is what F45 and rawhide ship, builds both books cleanly
here -- core-api at 1215 pages, admin-guide at 3074, no errors.  So F45 is
fine.

I will fix the constant either way.

Thanks,
Masaharu

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