[PATCH v2 0/3] fixes/improvements for top of docs/build-script

[PATCH v2 0/3] fixes/improvements for top of docs/build-script

[Mauro Carvalho Chehab]

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

[PATCH v2 1/3] tools/docs: sphinx-build-wrapper: fix compat with recent Tumbleweed

[Mauro Carvalho Chehab]

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>
---
 tools/docs/sphinx-build-wrapper | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index bd8e2ed746e7..98c4db5b7c47 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}"]
-- 
2.51.0

Re: [PATCH v2 1/3] tools/docs: sphinx-build-wrapper: fix compat with recent Tumbleweed

[Randy Dunlap]

Hi Mauro,


On 9/22/25 4:27 AM, Mauro Carvalho Chehab wrote:
> 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>
> ---
>   tools/docs/sphinx-build-wrapper | 25 ++++++++++++++++++++++---
>   1 file changed, 22 insertions(+), 3 deletions(-)

Works for me. Thanks.

Tested-by: Randy Dunlap <rdunlap@infradead.org>

-- 
~Randy

[PATCH v2 2/3] docs: Makefile: fix rustdoc detection

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/Makefile | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index cc4ee55c75ed..c60db1038c9c 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -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

[PATCH v2 3/3] tools/docs/sphinx-build-wrapper: allow skipping sphinx-build step

[Mauro Carvalho Chehab]

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.

Requested-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/linux-doc/5031e0c4-f17e-41b8-8955-959989e797f2@gmail.com/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/docs/sphinx-build-wrapper | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 98c4db5b7c47..cce985dced00 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -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

Re: [PATCH v2 0/3] fixes/improvements for top of docs/build-script

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

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

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

Thanks,

jon