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

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

[Masaharu Noguchi]

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.

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

Signed-off-by: Masaharu Noguchi <nogunix@gmail.com>
---
Verified on Debian 13 against the Sphinx/Docutils pairings listed in the
commit message: the warning fires for the ones whose pdfdocs build fails
and stays quiet for the ones that build, with the boundaries at Sphinx
9.1.0 and Docutils 0.21.2 checked explicitly.  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/
---
Changes in v2:
- MIN_DOCUTILS_SPHINX is now 9.1.0 rather than 9.0.0.  The limit that
  breaks these builds is sphinx-doc/sphinx#3099, which was fixed in
  9.1.0, so v1 silently skipped the whole 9.0.x series -- which does
  fail.  Caught by Akira Yokosawa.
- Reword the warning: Sphinx 9.0.x does declare support for Docutils
  0.22, so saying it "does not support" it was wrong.  It now says what
  actually breaks, scopes the claim to this documentation's literal
  blocks rather than stating a general rule, names both ways out, and
  follows the "Warning:" wording and layout the rest of the script uses.
  The docstring now covers both routes into the pairing, not just the
  distribution one.
- Commit message: give the mechanism -- Docutils 0.22 routes large
  literal includes into sphinxVerbatim, which is framed and so subject
  to the #3099 size limit -- rather than attributing the failure to a
  single package, per Mauro Carvalho Chehab's review.
- Commit message: extend the matrix with Sphinx 9.0.0, 9.0.4 and
  Docutils 0.23, and state the fixed LaTeX configuration all rows were
  measured under, since the 9.0.x rows show the pairing arises from
  upstream metadata with no distribution involved.
- Link to v1: https://lore.kernel.org/r/20260913-docs-sphinx-pre-install-docutils-v1-1-d923c769af91@gmail.com
---
 tools/docs/sphinx-pre-install | 79 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
index 965c9b093a41..fc024556f38c 100755
--- a/tools/docs/sphinx-pre-install
+++ b/tools/docs/sphinx-pre-install
@@ -41,6 +41,17 @@ from kdoc.python_version import PythonVersion
 RECOMMENDED_VERSION = PythonVersion("3.4.3").version
 MIN_PYTHON_VERSION = PythonVersion("3.7").version
 
+# Docutils 0.22 renders large literal blocks into sphinxVerbatim rather than
+# sphinxalltt, which puts them through framed.sty.  Sphinx's size limit on
+# that path is sphinx-doc/sphinx#3099, fixed only in the 9.1.0 release:
+#     https://github.com/sphinx-doc/sphinx/issues/3099
+# 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:
+#     https://github.com/orgs/sphinx-doc/discussions/14055
+MIN_DOCUTILS_SPHINX = PythonVersion("9.1.0").version
+DOCUTILS_BREAKS_AT = PythonVersion("0.22").version
+
 
 class DepManager:
     """
@@ -490,10 +501,78 @@ class MissingCheckers(AncillaryMethods):
             self.need_sphinx = 1
             return
 
+        # Check this before the version_check exit below: htmldocs invokes
+        # this script in that mode, and the warning has to reach it.
+        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 its LaTeX builder
+        cannot take at the sizes this documentation uses.
+
+        The pair arrives either way round: a distribution may relax the
+        upper bound Sphinx declares in order to ship a newer Docutils, and
+        Sphinx 9.0.x declares support for Docutils 0.22 itself while still
+        carrying the size limit that breaks these builds. Both still build
+        HTML, so nothing looks wrong until pdfdocs is run.
+        """
+        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)
+        breakver = PythonVersion.ver_str(DOCUTILS_BREAKS_AT)
+
+        print(f"Warning: Sphinx {curver} with Docutils {docver} produces\n" \
+              "   broken LaTeX for the large literal blocks in this\n" \
+              "   documentation: pdfdocs will fail. Building them needs\n" \
+              f"   Sphinx {minver} or later, or Docutils below {breakver}.\n" \
+              "   HTML builds are unaffected.")
+
     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>