From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: Mon, 22 Sep 2025 11:27:38 +0000 (+0200)
Subject: tools/docs: sphinx-build-wrapper: fix compat with recent Tumbleweed
X-Git-Tag: v6.19-rc1~184^2~60^2~7
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=35b9d338e40142c71b7270cc69b2b5fa1f24cc29;p=thirdparty%2Fkernel%2Flinux.git

tools/docs: sphinx-build-wrapper: fix compat with recent Tumbleweed

On recent versions of openSUSE Tumbleweed, sphinx-buildis is no longer
a Python script, but something else. Such change is due to how
it now handles alternatives:

    https://en.opensuse.org/openSUSE:Migrating_to_libalternatives_with_alts

The most common approach that distros use for alternatives is via
symlinks:

    lrwxrwxrwx 1 root root 22 out 31  2024 /usr/bin/java -> /etc/alternatives/java
    lrwxrwxrwx 1 root root 37 mar  5  2025 /etc/alternatives/java -> /usr/lib/jvm/java-21-openjdk/bin/java

With such approach, one can sun the script with either:

    <sphinx>
    python3 <script>

However, openSUSE's implementation uses an ELF binary (/usr/bin/alts),
which breaks the latter format.

It is needed to allow users to specify the Python version to be
used while building docs, as some distros like Leap 15.x are
shipped with:

- older, unsupported python3/python3-sphinx packages;
- more modern python3xx/python3xx-sphinx packages that work
  properly.

On such distros, building docs require running make with:

    make PYTHON3=python3.11 htmldocs

Heh, even on more moderen distros where python3-sphinx
is supported, one may still want to use a newer package,
for instance, due to performance issues, as:

    - with Python < 3.11, kernel-doc is 3 times slower;
    - while building htmldocs with Python 3.13/Sphinx 8.x
      takes about 3 minutes on a modern machine, using
      Sphinx < 8.0 can take up to 16 minutes to build docs
      (7.x are the worse ones and require lots of RAM).

So, even with not too old distros, one still may want to use
for instance PYTHON3=python3.11.

To acommodate using PYTHON3 without breaking on Tumbleweed,
add a workaround that will only use:

    $(PYTHON3) sphinx-build

if PYTHON3 env var is not default.

While here, drop the special check for venv, as, with venv,
we can just call sphinx-build directly without any extra
checks.

Reported-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/all/883df949-0281-4a39-8745-bcdcce3a5594@infradead.org/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <8917f862e0b8484c68408c274129c9f37a7aefb4.1758539031.git.mchehab+huawei@kernel.org>
---

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index bd8e2ed746e78..98c4db5b7c47b 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -185,6 +185,19 @@ class SphinxBuilder:
         self.kernelrelease = os.environ.get("KERNELRELEASE", "unknown")
         self.pdflatex = os.environ.get("PDFLATEX", "xelatex")
 
+        #
+        # Kernel main Makefile defines a PYTHON3 variable whose default is
+        # "python3". When set to a different value, it allows running a
+        # diferent version than the default official python3 package.
+        # Several distros package python3xx-sphinx packages with newer
+        # versions of Python and sphinx-build.
+        #
+        # Honor such variable different than default
+        #
+        self.python = os.environ.get("PYTHON3")
+        if self.python == "python3":
+            self.python = None
+
         if not interactive:
             self.latexopts = os.environ.get("LATEXOPTS", "-interaction=batchmode -no-shell-escape")
         else:
@@ -272,10 +285,16 @@ class SphinxBuilder:
             if self.n_jobs:
                 n_jobs = str(self.n_jobs)
 
-            if self.venv:
-                cmd = ["python"]
+            #
+            # We can't simply call python3 sphinx-build, as OpenSUSE
+            # Tumbleweed uses an ELF binary file (/usr/bin/alts) to switch
+            # between different versions of sphinx-build. So, only call it
+            # prepending "python3.xx" when PYTHON3 variable is not default.
+            #
+            if self.python:
+                cmd = [self.python]
             else:
-                cmd = [sys.executable]
+                cmd = []
 
             cmd += [sphinx_build]
             cmd += [f"-j{n_jobs}"]