mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
* [PATCH] docs: sphinx-pre-install: warn about unsupported Docutils versions
@ 2026-09-13  3:13 Masaharu Noguchi
  2026-09-14  4:56 ` Akira Yokosawa
  2026-09-14  5:42 ` Mauro Carvalho Chehab
  0 siblings, 2 replies; 5+ messages in thread
From: Masaharu Noguchi @ 2026-09-13  3:13 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Jonathan Corbet, Shuah Khan, Randy Dunlap
  Cc: Akira Yokosawa, Chen Miao, Bagas Sanjaya, linux-doc,
	linux-kernel, 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>


^ permalink raw reply	[flat|nested] 5+ messages in thread
end of thread, other threads:[~2026-09-14  9:52 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2026-09-13  3:13 [PATCH] docs: sphinx-pre-install: warn about unsupported Docutils versions Masaharu Noguchi
2026-09-14  4:56 ` Akira Yokosawa
2026-09-14  9:19   ` Masaharu Noguchi
2026-09-14  5:42 ` Mauro Carvalho Chehab
2026-09-14  9:52   ` Masaharu Noguchi

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®