fixes/improvements for top of docs/build-script

Hi Jon,

This series contain the 3 patches against build-script I sent in separate:

- patch 1 solves a problem with Tumbleweed build. I opted to be verbose at the comments to properly describe what we're addressing and why;
- patch 2 solves an issue that sometimes happen on my machine while checking for CONFIG_RUST=y;
- patch 3 contains a request from Akira to allow running just the PDF step when pdfdocs target is selected.

on patch 3, I opted to not modify Makefile, as I don't see why most people would want to proceed with PDF builds when latex build fails. For those who want such feature, e. g. simulate "make -i pdfdocs" behavior, all it is needed after the change is to run:

	tools/docs/sphinx-build-wrapper latexdocs || echo "LaTeX error: $?"
	tools/docs/sphinx-build-wrapper -s pdfdocs

eventually adding some extra flags to the second command from the command line arguments below:

  --paper {,a4,letter}  Paper size for LaTeX/PDF output
  --deny-vf DENY_VF     Configuration to deny variable fonts on pdf builds
  -v, --verbose         place build in verbose mode
  -j, --jobs JOBS       Sets number of jobs to use with sphinx-build
  -i, --interactive     Change latex default to run in interactive mode

-s, --skip-sphinx-build
Skip sphinx-build step

E.g. running the second step with, for instance, with:

	tools/docs/sphinx-build-wrapper -v -s -i --deny-vf ~/.my-deny pdfdocs

to:
- assume that sphinx-build --builder latex was already executed (-s);
- provide a summary of what PDF files were built at the end (-v);
- run LaTeX in interactive mode in case of errors (-i);
- use a custom deny-list for variable fonts (--deny-vf).

If we add this at docs Makefile, and allow all possible alternatives, this would just add uneeded complexity there, IMO.

Mauro Carvalho Chehab (3):
tools/docs: sphinx-build-wrapper: fix compat with recent Tumbleweed
docs: Makefile: fix rustdoc detection tools/docs/sphinx-build-wrapper: allow skipping sphinx-build step

 Documentation/Makefile          |  4 ++-
 tools/docs/sphinx-build-wrapper | 43 ++++++++++++++++++++++++++-------
 2 files changed, 37 insertions(+), 10 deletions(-)

2.51.0

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.

---
 tools/docs/sphinx-build-wrapper | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

index bd8e2ed746e7..98c4db5b7c47 100755
@@ -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}"]

2.51.0

Hi Mauro,

Works for me. Thanks.

~Randy

During cleanups, the logic checking if .config exists were dropped, but removing it causes false-positives. So, re-add it.

---
 Documentation/Makefile | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

index cc4ee55c75ed..c60db1038c9c 100644
@@ -42,8 +42,10 @@ FONTS_CONF_DENY_VF ?= $(HOME)/deny-vf
 # User-friendly check for sphinx-build
 HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
 
+ifneq ($(wildcard $(srctree)/.config),)
 ifeq ($(CONFIG_RUST),y)
-	RUSTDOC="--rustdoc"
+	RUSTDOC=--rustdoc
+endif
 endif
 
 ifeq ($(HAVE_SPHINX),0)

2.51.0

Most targets have two steps:
- step 1: run sphinx-build;
- step 2: run a post-build logic.

The second step can be as simple as copying static files like CSS, but may may also envolve running make. allowing to skip the first step helps debugging what's broken, and also allows using make command line arguments like --ignore-errors.

Add an option to skip step 1.

---
 tools/docs/sphinx-build-wrapper | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

index 98c4db5b7c47..cce985dced00 100755
@@ -622,7 +622,8 @@ class SphinxBuilder:
         shutil.rmtree(self.builddir, ignore_errors=True)
 
     def build(self, target, sphinxdirs=None,
-              theme=None, css=None, paper=None, deny_vf=None, rustdoc=False):
+              theme=None, css=None, paper=None, deny_vf=None, rustdoc=False,
+              skip_sphinx=False):
         """
         Build documentation using Sphinx. This is the core function of this
         module. It prepares all arguments required by sphinx-build.

@@ -644,9 +645,10 @@ class SphinxBuilder:
         #
         # Other targets require sphinx-build, so check if it exists
         #
-        sphinxbuild = shutil.which(self.sphinxbuild, path=self.env["PATH"])
-        if not sphinxbuild and target != "mandocs":
-            sys.exit(f"Error: {self.sphinxbuild} not found in PATH.\n")
+        if not skip_sphinx:
+            sphinxbuild = shutil.which(self.sphinxbuild, path=self.env["PATH"])
+            if not sphinxbuild and target != "mandocs":
+                sys.exit(f"Error: {self.sphinxbuild} not found in PATH.\n")
 
         if builder == "latex":
             if not self.pdflatex_cmd and not self.latexmk_cmd:

@@ -732,7 +734,7 @@ class SphinxBuilder:
 
             if target == "mandocs":
                 self.handle_man(kerneldoc, docs_dir, src_dir, output_dir)
-            else:
+            elif not skip_sphinx:
                 try:
                     result = self.run_sphinx(sphinxbuild, build_args,
                                              env=self.env)

@@ -814,6 +816,9 @@ def main():
     parser.add_argument('-i', '--interactive', action='store_true',
                         help="Change latex default to run in interactive mode")
 
+    parser.add_argument('-s', '--skip-sphinx-build', action='store_true',
+                        help="Skip sphinx-build step")
+
     parser.add_argument("-V", "--venv", nargs='?', const=f'{VENV_DEFAULT}',
                         default=None,
                         help=f'If used, run Sphinx from a venv dir (default dir: {VENV_DEFAULT})')

@@ -829,7 +834,8 @@ def main():
 
     builder.build(args.target, sphinxdirs=args.sphinxdirs,
                   theme=args.theme, css=args.css, paper=args.paper,
-                  rustdoc=args.rustdoc, deny_vf=args.deny_vf)
+                  rustdoc=args.rustdoc, deny_vf=args.deny_vf,
+                  skip_sphinx=args.skip_sphinx_build)
 
 if __name__ == "__main__":
     main()

2.51.0

OK, I've applied this set to the build-script branch.

Thanks,

jon