[PATCH 0/2] A couple patches for sphinx-build-wrapper

[PATCH 0/2] A couple patches for sphinx-build-wrapper

[Mauro Carvalho Chehab]

Hi Jon,

This small series is against docs/build-script branch.

The first patch addresses the lack of a check after running
sphinx-build to see if it returned some error code.

The second patch is a bonus cleanup: it get rids with
load_config.py, replacing it by a single line at conf.py,
simplifying even further docs Makefile. Thanks for
reminding me about that legacy code that we can drop!

-

I didn't implement yet Akira's suggestion of having a way
to use make -i to ignore errors from latexdocs while
doing pdf builds. I have a couple of ideas on my head.

I'm tempting to implement a:

    --no-sphinx

command line argument at sphinx-build-wrapper, which would
make it ignore the sphinx-build step. this way a makefile
rule like:

    pdf-after-latex: latexdocs
        +$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ $(RUSTDOC) \
                --sphinxdirs="$(SPHINXDIRS)" \
                --builddir="$(BUILDDIR)" --deny-vf=$(FONTS_CONF_DENY_VF) \
                --css=$(DOCS_CSS) --paper=$(PAPER) --no-sphinx

would allow people to play with "-i", "-k", "--output-sync" and
other make arguments.

However, Friday's happy hour is quickly approaching here... Not the
best time to implement new ideas :-D

I'll try to materialize it next week.

Have a nice weekend!
Mauro

Mauro Carvalho Chehab (2):
  tools/docs: sphinx-build-wrapper: handle sphinx-build errors
  docs: conf.py: get rid of load_config.py

 Documentation/Makefile              |  4 --
 Documentation/conf.py               | 15 +++-----
 Documentation/sphinx/load_config.py | 60 -----------------------------
 tools/docs/sphinx-build-wrapper     |  9 ++++-
 4 files changed, 12 insertions(+), 76 deletions(-)
 delete mode 100644 Documentation/sphinx/load_config.py

-- 
2.51.0

[PATCH 1/2] tools/docs: sphinx-build-wrapper: handle sphinx-build errors

[Mauro Carvalho Chehab]

If sphinx-build returns an error, exit the script.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/docs/sphinx-build-wrapper | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 6ed3d58ec277..b7e97c10d7dc 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -275,7 +275,7 @@ class SphinxBuilder:
             if self.venv:
                 cmd = ["python"]
             else:
-                cmd = [sys.executable,]
+                cmd = [sys.executable]
 
             cmd += [sphinx_build]
             cmd += [f"-j{n_jobs}"]
@@ -718,7 +718,12 @@ class SphinxBuilder:
                 self.handle_man(kerneldoc, docs_dir, src_dir, output_dir)
             else:
                 try:
-                    self.run_sphinx(sphinxbuild, build_args, env=self.env)
+                    result = self.run_sphinx(sphinxbuild, build_args,
+                                             env=self.env)
+
+                    if result:
+                        sys.exit(f"Build failed: return code: {result}")
+
                 except (OSError, ValueError, subprocess.SubprocessError) as e:
                     sys.exit(f"Build failed: {repr(e)}")
 
-- 
2.51.0

[PATCH 2/2] docs: conf.py: get rid of load_config.py

[Mauro Carvalho Chehab]

The code here was meant to handle 3 functions:
1. allow having a separate conf.py file, per subdir;
2. generate a list of latex documents.
3. set "subproject" tag if SPHINXDIRS points to a subdir.

We don't have (1) anymore, and (3) is now properly handled
entirely inside conf.py.

So, only (3) is still needed, and this is a single-line change
at conf.py.

So, drop it, moving the remaining code to conf.py.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/Makefile              |  4 --
 Documentation/conf.py               | 15 +++-----
 Documentation/sphinx/load_config.py | 60 -----------------------------
 3 files changed, 5 insertions(+), 74 deletions(-)
 delete mode 100644 Documentation/sphinx/load_config.py

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 6ccd5db1dcbd..9663e7a31feb 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -24,7 +24,6 @@ SPHINXDIRS    = .
 DOCS_THEME    =
 DOCS_CSS      =
 RUSTDOC       =
-SPHINX_CONF   = conf.py
 PAPER         =
 BUILDDIR      = $(obj)/output
 PDFLATEX      = xelatex
@@ -108,9 +107,6 @@ dochelp:
 	@echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
 	@echo  '  valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
 	@echo
-	@echo  '  make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
-	@echo  '  configuration. This is e.g. useful to build with nit-picking config.'
-	@echo
 	@echo  '  make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.'
 	@echo
 	@echo  '  make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.'
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 574896cca198..1ea2ae5c6276 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -18,8 +18,6 @@ import sphinx
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath("sphinx"))
 
-from load_config import loadConfig               # pylint: disable=C0413,E0401
-
 # Minimal supported version
 needs_sphinx = "3.4.3"
 
@@ -93,8 +91,12 @@ def config_init(app, config):
     # LaTeX and PDF output require a list of documents with are dependent
     # of the app.srcdir. Add them here
 
-    # When SPHINXDIRS is used, we just need to get index.rst, if it exists
+    # Handle the case where SPHINXDIRS is used
     if not os.path.samefile(doctree, app.srcdir):
+        # Add a tag to mark that the build is actually a subproject
+        tags.add("subproject")
+
+        # get index.rst, if it exists
         doc = os.path.basename(app.srcdir)
         fname = "index"
         if os.path.exists(os.path.join(app.srcdir, fname + ".rst")):
@@ -583,13 +585,6 @@ pdf_documents = [
 kerneldoc_bin = "../scripts/kernel-doc.py"
 kerneldoc_srctree = ".."
 
-# ------------------------------------------------------------------------------
-# Since loadConfig overwrites settings from the global namespace, it has to be
-# the last statement in the conf.py file
-# ------------------------------------------------------------------------------
-loadConfig(globals())
-
-
 def setup(app):
     """Patterns need to be updated at init time on older Sphinx versions"""
 
diff --git a/Documentation/sphinx/load_config.py b/Documentation/sphinx/load_config.py
deleted file mode 100644
index 1afb0c97f06b..000000000000
--- a/Documentation/sphinx/load_config.py
+++ /dev/null
@@ -1,60 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-# SPDX-License-Identifier: GPL-2.0
-# pylint: disable=R0903, C0330, R0914, R0912, E0401
-
-import os
-import sys
-from sphinx.util.osutil import fs_encoding
-
-# ------------------------------------------------------------------------------
-def loadConfig(namespace):
-# ------------------------------------------------------------------------------
-
-    """Load an additional configuration file into *namespace*.
-
-    The name of the configuration file is taken from the environment
-    ``SPHINX_CONF``. The external configuration file extends (or overwrites) the
-    configuration values from the origin ``conf.py``.  With this you are able to
-    maintain *build themes*.  """
-
-    config_file = os.environ.get("SPHINX_CONF", None)
-    if (config_file is not None
-        and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ):
-        config_file = os.path.abspath(config_file)
-
-        # Let's avoid one conf.py file just due to latex_documents
-        start = config_file.find('Documentation/')
-        if start >= 0:
-            start = config_file.find('/', start + 1)
-
-        end = config_file.rfind('/')
-        if start >= 0 and end > 0:
-            dir = config_file[start + 1:end]
-
-            print("source directory: %s" % dir)
-            new_latex_docs = []
-            latex_documents = namespace['latex_documents']
-
-            for l in latex_documents:
-                if l[0].find(dir + '/') == 0:
-                    has = True
-                    fn = l[0][len(dir) + 1:]
-                    new_latex_docs.append((fn, l[1], l[2], l[3], l[4]))
-                    break
-
-            namespace['latex_documents'] = new_latex_docs
-
-        # If there is an extra conf.py file, load it
-        if os.path.isfile(config_file):
-            sys.stdout.write("load additional sphinx-config: %s\n" % config_file)
-            config = namespace.copy()
-            config['__file__'] = config_file
-            with open(config_file, 'rb') as f:
-                code = compile(f.read(), fs_encoding, 'exec')
-                exec(code, config)
-            del config['__file__']
-            namespace.update(config)
-        else:
-            config = namespace.copy()
-            config['tags'].add("subproject")
-            namespace.update(config)
-- 
2.51.0

Re: [PATCH 2/2] docs: conf.py: get rid of load_config.py

[Jonathan Corbet]

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

> The code here was meant to handle 3 functions:
> 1. allow having a separate conf.py file, per subdir;
> 2. generate a list of latex documents.
> 3. set "subproject" tag if SPHINXDIRS points to a subdir.
>
> We don't have (1) anymore, and (3) is now properly handled
> entirely inside conf.py.
>
> So, only (3) is still needed, and this is a single-line change
> at conf.py.
>
> So, drop it, moving the remaining code to conf.py.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/Makefile              |  4 --
>  Documentation/conf.py               | 15 +++-----
>  Documentation/sphinx/load_config.py | 60 -----------------------------
>  3 files changed, 5 insertions(+), 74 deletions(-)
>  delete mode 100644 Documentation/sphinx/load_config.py
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 6ccd5db1dcbd..9663e7a31feb 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -24,7 +24,6 @@ SPHINXDIRS    = .
>  DOCS_THEME    =
>  DOCS_CSS      =
>  RUSTDOC       =
> -SPHINX_CONF   = conf.py
>  PAPER         =
>  BUILDDIR      = $(obj)/output
>  PDFLATEX      = xelatex
> @@ -108,9 +107,6 @@ dochelp:
>  	@echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
>  	@echo  '  valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
>  	@echo
> -	@echo  '  make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
> -	@echo  '  configuration. This is e.g. useful to build with nit-picking config.'
> -	@echo
>  	@echo  '  make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.'

So probably I'm a little slow today, but this confuses me.  Even after
this change, the makefile still uses SPHINX_CONF, so I'm not sure how it
is supposed to be set?

Thanks,

jon

Re: [PATCH 2/2] docs: conf.py: get rid of load_config.py

[Mauro Carvalho Chehab]

Em Fri, 19 Sep 2025 15:38:56 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > The code here was meant to handle 3 functions:
> > 1. allow having a separate conf.py file, per subdir;
> > 2. generate a list of latex documents.
> > 3. set "subproject" tag if SPHINXDIRS points to a subdir.
> >
> > We don't have (1) anymore, and (3) is now properly handled
> > entirely inside conf.py.
> >
> > So, only (3) is still needed, and this is a single-line change
> > at conf.py.
> >
> > So, drop it, moving the remaining code to conf.py.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  Documentation/Makefile              |  4 --
> >  Documentation/conf.py               | 15 +++-----
> >  Documentation/sphinx/load_config.py | 60 -----------------------------
> >  3 files changed, 5 insertions(+), 74 deletions(-)
> >  delete mode 100644 Documentation/sphinx/load_config.py
> >
> > diff --git a/Documentation/Makefile b/Documentation/Makefile
> > index 6ccd5db1dcbd..9663e7a31feb 100644
> > --- a/Documentation/Makefile
> > +++ b/Documentation/Makefile
> > @@ -24,7 +24,6 @@ SPHINXDIRS    = .
> >  DOCS_THEME    =
> >  DOCS_CSS      =
> >  RUSTDOC       =
> > -SPHINX_CONF   = conf.py
> >  PAPER         =
> >  BUILDDIR      = $(obj)/output
> >  PDFLATEX      = xelatex
> > @@ -108,9 +107,6 @@ dochelp:
> >  	@echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
> >  	@echo  '  valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
> >  	@echo
> > -	@echo  '  make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
> > -	@echo  '  configuration. This is e.g. useful to build with nit-picking config.'
> > -	@echo
> >  	@echo  '  make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.'  
> 
> So probably I'm a little slow today, but this confuses me.  Even after
> this change, the makefile still uses SPHINX_CONF, so I'm not sure how it
> is supposed to be set?

Heh, incomplete patch, sorry for that. I'll send a v2 of this series.


Thanks,
Mauro