Skip to contentSkip to conversation

A couple patches for sphinx-build-wrapper

PATCH Superseded Mauro Carvalho Chehab 2 participants 5 messages Sep 19, 2025 – Sep 20, 2025

Subsystems (2)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover A couple patches for sphinx-build-wrapper

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
Signature · 1 line
2.51.0
#1 lore raw

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

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

---
 tools/docs/sphinx-build-wrapper | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
tools/docs/sphinx-build-wrapper +7 -2
index 6ed3d58ec277..b7e97c10d7dc 100755
@@ -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)}")
 
Signature · 1 line
2.51.0
#2 lore raw

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

In reply to 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.

---
 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
Documentation/Makefile +0 -4
index 6ccd5db1dcbd..9663e7a31feb 100644
@@ -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.'
Documentation/conf.py +5 -10
index 574896cca198..1ea2ae5c6276 100644
@@ -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"""
 
Documentation/sphinx/load_config.py deleted +0 -60

60 lines not on this page · raw message

Signature · 1 line
2.51.0
maintainer
#3 lore raw

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

Quoted 34 lines · 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.

---
 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
Documentation/Makefile +0 -1
index 6ccd5db1dcbd..9663e7a31feb 100644
@@ -24,7 +24,6 @@ SPHINXDIRS    = .
 DOCS_THEME    =
 DOCS_CSS      =
 RUSTDOC       =
-SPHINX_CONF   = conf.py
 PAPER         =
 BUILDDIR      = $(obj)/output
 PDFLATEX      = xelatex

Documentation/Makefile dochelp: · line 110

Quoted 7 lines
Documentation/Makefile +0 -3
@@ -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

#4 lore raw

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

Em Fri, 19 Sep 2025 15:38:56 -0600
Jonathan Corbet <[email protected]> escreveu:

Quoted 39 lines
Quoted 37 lines · 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.

---
 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
Documentation/Makefile +0 -1
index 6ccd5db1dcbd..9663e7a31feb 100644
@@ -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
Quoted 8 lines

Documentation/Makefile dochelp: · line 110

Quoted 4 lines
Documentation/Makefile +0 -3
-	@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