A couple patches for sphinx-build-wrapper
Subsystems (2)
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-sphinxwould 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
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
@@ -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
PATCH 2/2 docs: conf.py: get rid of load_config.py
In reply to Mauro Carvalho ChehabThe 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
@@ -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
@@ -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
Jonathan Corbet
maintainerRe: [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 separateconf.pyfile, 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 <[email protected]>--- 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.pyDocumentation/Makefile +0
-1@@ -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
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 separateconf.pyfile, 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 <[email protected]>--- 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.pyDocumentation/Makefile +0
-1@@ -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