[PATCH 0/4] tools/docs: sphinx-build-wrapper: avoid spurious rust docs generation

[PATCH 0/4] tools/docs: sphinx-build-wrapper: avoid spurious rust docs generation

[Thomas Weißschuh]

Currently the rust docs are generated for each entry of SPHINXDIRS,
even those not mentioning the rust directory.

Only generate the rust docs only once and only when requested.

Signed-off-by: Thomas Weißschuh <linux@weissschuh.net>
---
Thomas Weißschuh (4):
      tools/docs: sphinx-build-wrapper: generate rust docs only once
      tools/docs: sphinx-build-wrapper: make 'rustdoc' a local variable
      tools/docs: sphinx-build-wrapper: compute sphinxdirs_list earlier
      tools/docs: sphinx-build-wrapper: only generate rust docs when requested

 tools/docs/sphinx-build-wrapper | 80 +++++++++++++++++++++--------------------
 1 file changed, 41 insertions(+), 39 deletions(-)
---
base-commit: e1a8301cd941b8029893500e6857d7978873483f
change-id: 20260117-docs-spurious-rust-8ffa2748925c

Best regards,
-- 
Thomas Weißschuh <linux@weissschuh.net>

[PATCH 1/4] tools/docs: sphinx-build-wrapper: generate rust docs only once

[Thomas Weißschuh]

Currently the rust docs are generated for each entry in SPHINXDIRS.
This is unnecessary as they will be the same for each one.

Move the generation, so it is executed only once.

Signed-off-by: Thomas Weißschuh <linux@weissschuh.net>
---
 tools/docs/sphinx-build-wrapper | 34 +++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 7a5fcef25429..4ce655a31061 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -352,23 +352,6 @@ class SphinxBuilder:
             except (OSError, IOError) as e:
                 print(f"Warning: Failed to copy CSS: {e}", file=sys.stderr)
 
-        if self.rustdoc:
-            print("Building rust docs")
-            if "MAKE" in self.env:
-                cmd = [self.env["MAKE"]]
-            else:
-                cmd = ["make", "LLVM=1"]
-
-            cmd += [ "rustdoc"]
-            if self.verbose:
-                print(" ".join(cmd))
-
-            try:
-                subprocess.run(cmd, check=True)
-            except subprocess.CalledProcessError as e:
-                print(f"Ignored errors when building rustdoc: {e}. Is RUST enabled?",
-                      file=sys.stderr)
-
     def build_pdf_file(self, latex_cmd, from_dir, path):
         """Builds a single pdf file using latex_cmd"""
         try:
@@ -786,6 +769,23 @@ class SphinxBuilder:
         elif target == "infodocs":
             self.handle_info(output_dirs)
 
+        if self.rustdoc and target in ["htmldocs", "epubdocs"]:
+            print("Building rust docs")
+            if "MAKE" in self.env:
+                cmd = [self.env["MAKE"]]
+            else:
+                cmd = ["make", "LLVM=1"]
+
+            cmd += [ "rustdoc"]
+            if self.verbose:
+                print(" ".join(cmd))
+
+            try:
+                subprocess.run(cmd, check=True)
+            except subprocess.CalledProcessError as e:
+                print(f"Ignored errors when building rustdoc: {e}. Is RUST enabled?",
+                      file=sys.stderr)
+
 def jobs_type(value):
     """
     Handle valid values for -j. Accepts Sphinx "-jauto", plus a number

-- 
2.52.0

[PATCH 2/4] tools/docs: sphinx-build-wrapper: make 'rustdoc' a local variable

[Thomas Weißschuh]

All users of this variable are now in the same method.

Demote the instance variable to a local one.

Signed-off-by: Thomas Weißschuh <linux@weissschuh.net>
---
 tools/docs/sphinx-build-wrapper | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 4ce655a31061..5f956c289c02 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -123,12 +123,10 @@ class SphinxBuilder:
         """
         Checks if Rust is enabled
         """
-        self.rustdoc = False
-
         config = os.path.join(self.srctree, ".config")
 
         if not os.path.isfile(config):
-            return
+            return False
 
         re_rust = re.compile(r"CONFIG_RUST=(m|y)")
 
@@ -136,11 +134,13 @@ class SphinxBuilder:
             with open(config, "r", encoding="utf-8") as fp:
                 for line in fp:
                     if re_rust.match(line):
-                        self.rustdoc = True
-                        return
+                        return True
 
         except OSError as e:
             print(f"Failed to open {config}", file=sys.stderr)
+            return False
+
+        return False
 
     def get_sphinx_extra_opts(self, n_jobs):
         """
@@ -259,8 +259,6 @@ class SphinxBuilder:
 
         self.get_sphinx_extra_opts(n_jobs)
 
-        self.check_rust()
-
         #
         # If venv command line argument is specified, run Sphinx from venv
         #
@@ -680,7 +678,8 @@ class SphinxBuilder:
 
             args.extend(["-D", f"latex_elements.papersize={paper}paper"])
 
-        if self.rustdoc:
+        rustdoc = self.check_rust()
+        if rustdoc:
             args.extend(["-t", "rustdoc"])
 
         if not sphinxdirs:
@@ -769,7 +768,7 @@ class SphinxBuilder:
         elif target == "infodocs":
             self.handle_info(output_dirs)
 
-        if self.rustdoc and target in ["htmldocs", "epubdocs"]:
+        if rustdoc and target in ["htmldocs", "epubdocs"]:
             print("Building rust docs")
             if "MAKE" in self.env:
                 cmd = [self.env["MAKE"]]

-- 
2.52.0

[PATCH 3/4] tools/docs: sphinx-build-wrapper: compute sphinxdirs_list earlier

[Thomas Weißschuh]

An upcoming patch will require sphinxdirs_list to be available before
the call to check_rust().

Move it up in the function.

Signed-off-by: Thomas Weißschuh <linux@weissschuh.net>
---
 tools/docs/sphinx-build-wrapper | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 5f956c289c02..a3cca4634355 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -670,6 +670,19 @@ class SphinxBuilder:
         if kerneldoc.startswith(self.srctree):
             kerneldoc = os.path.relpath(kerneldoc, self.srctree)
 
+        if not sphinxdirs:
+            sphinxdirs = os.environ.get("SPHINXDIRS", ".")
+
+        #
+        # sphinxdirs can be a list or a whitespace-separated string
+        #
+        sphinxdirs_list = []
+        for sphinxdir in sphinxdirs:
+            if isinstance(sphinxdir, list):
+                sphinxdirs_list += sphinxdir
+            else:
+                sphinxdirs_list += sphinxdir.split()
+
         args = [ "-b", builder, "-c", docs_dir ]
 
         if builder == "latex":
@@ -682,9 +695,6 @@ class SphinxBuilder:
         if rustdoc:
             args.extend(["-t", "rustdoc"])
 
-        if not sphinxdirs:
-            sphinxdirs = os.environ.get("SPHINXDIRS", ".")
-
         #
         # The sphinx-build tool has a bug: internally, it tries to set
         # locale with locale.setlocale(locale.LC_ALL, ''). This causes a
@@ -695,16 +705,6 @@ class SphinxBuilder:
         except locale.Error:
             self.env["LC_ALL"] = "C"
 
-        #
-        # sphinxdirs can be a list or a whitespace-separated string
-        #
-        sphinxdirs_list = []
-        for sphinxdir in sphinxdirs:
-            if isinstance(sphinxdir, list):
-                sphinxdirs_list += sphinxdir
-            else:
-                sphinxdirs_list += sphinxdir.split()
-
         #
         # Step 1:  Build each directory in separate.
         #

-- 
2.52.0

[PATCH 4/4] tools/docs: sphinx-build-wrapper: only generate rust docs when requested

[Thomas Weißschuh]

When the user explicitly specifies SPHINXDIRS to build a specific
subdirectory it is unexpected that the rust docs are also generated.
Especially as their generation may dominate the execution time.

Only generate the rust docs when they are part of the SPHINXDIRS
requested by the user. 'rust/rustdocs' is not considered, as it is
not a valid SPHINXDIRS anyways.

Signed-off-by: Thomas Weißschuh <linux@weissschuh.net>
---
 tools/docs/sphinx-build-wrapper | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index a3cca4634355..f817497bb706 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -119,12 +119,15 @@ class SphinxBuilder:
 
         return path
 
-    def check_rust(self):
+    def check_rust(self, sphinxdirs):
         """
         Checks if Rust is enabled
         """
         config = os.path.join(self.srctree, ".config")
 
+        if not {'.', 'rust'}.intersection(sphinxdirs):
+            return False
+
         if not os.path.isfile(config):
             return False
 
@@ -691,7 +694,7 @@ class SphinxBuilder:
 
             args.extend(["-D", f"latex_elements.papersize={paper}paper"])
 
-        rustdoc = self.check_rust()
+        rustdoc = self.check_rust(sphinxdirs_list)
         if rustdoc:
             args.extend(["-t", "rustdoc"])
 

-- 
2.52.0

Re: [PATCH 0/4] tools/docs: sphinx-build-wrapper: avoid spurious rust docs generation

[Mauro Carvalho Chehab]

On Sun, 18 Jan 2026 00:26:20 +0100
Thomas Weißschuh <linux@weissschuh.net> wrote:

> Currently the rust docs are generated for each entry of SPHINXDIRS,
> even those not mentioning the rust directory.
> 
> Only generate the rust docs only once and only when requested.
> 
> Signed-off-by: Thomas Weißschuh <linux@weissschuh.net>
> ---
> Thomas Weißschuh (4):
>       tools/docs: sphinx-build-wrapper: generate rust docs only once
>       tools/docs: sphinx-build-wrapper: make 'rustdoc' a local variable
>       tools/docs: sphinx-build-wrapper: compute sphinxdirs_list earlier
>       tools/docs: sphinx-build-wrapper: only generate rust docs when requested
> 
>  tools/docs/sphinx-build-wrapper | 80 +++++++++++++++++++++--------------------
>  1 file changed, 41 insertions(+), 39 deletions(-)

Patches in this series look ok. Code reviewed and I also did some
tests, and all LGTM.

So, for this series:

[mchehab: tested building with and without config RUST, doing
 a full build and also passing --sphinxdirs rust peci and just
 --sphinxdirs rust]

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Thanks,
Mauro

Re: [PATCH 0/4] tools/docs: sphinx-build-wrapper: avoid spurious rust docs generation

[Jonathan Corbet]

Thomas Weißschuh <linux@weissschuh.net> writes:

> Currently the rust docs are generated for each entry of SPHINXDIRS,
> even those not mentioning the rust directory.
>
> Only generate the rust docs only once and only when requested.
>
> Signed-off-by: Thomas Weißschuh <linux@weissschuh.net>
> ---
> Thomas Weißschuh (4):
>       tools/docs: sphinx-build-wrapper: generate rust docs only once
>       tools/docs: sphinx-build-wrapper: make 'rustdoc' a local variable
>       tools/docs: sphinx-build-wrapper: compute sphinxdirs_list earlier
>       tools/docs: sphinx-build-wrapper: only generate rust docs when requested
>
>  tools/docs/sphinx-build-wrapper | 80 +++++++++++++++++++++--------------------
>  1 file changed, 41 insertions(+), 39 deletions(-)

Applied, thanks.

jon