some fixes for docs Makefile
Subsystems (2)
cover some fixes for docs Makefile
Hi Jon,
Another small series against build-script branch with fixes.
The first one removes bogus warnings when latex is not installed. The second one has a small fix to avoid writing *.pyc cache at the source dir.
Mauro Carvalho Chehab (2):
tools/docs/sphinx-build-wrapper: allow skipping sphinx-build step
docs: Makefile: avoid a warning when using without texlive
Documentation/Makefile | 13 ++++--------- tools/docs/sphinx-build-wrapper | 18 ++++++++++++------ 2 files changed, 16 insertions(+), 15 deletions(-)
Signature · 1 line
2.51.0
PATCH 1/2 tools/docs/sphinx-build-wrapper: allow skipping sphinx-build step
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.
--- tools/docs/sphinx-build-wrapper | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-)
tools/docs/sphinx-build-wrapper +12 -6
@@ -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()
Signature · 1 line
2.51.0
PATCH 2/2 docs: Makefile: avoid a warning when using without texlive
In reply to Mauro Carvalho ChehabAs reported by Randy, running make htmldocs on a machine without textlive now produce warnings:
$ make O=DOCS htmldocs
../Documentation/Makefile:70: warning: overriding recipe for target 'pdfdocs'
../Documentation/Makefile:61: warning: ignoring old recipe for target 'pdfdocs'That's because the code has now two definitions for pdfdocs in case $PDFLATEX command is not found. With the new script, such special case is not needed anymore, as the script checks it.
Drop the special case. Even after dropping it, on a machine without LaTeX, it will still produce an error as expected, as running:
$ ./tools/docs/sphinx-build-wrapper pdfdocs
Error: pdflatex or latexmk required for PDF generationdoes the check. After applying the patch we have:
$ make SPHINXDIRS=peci htmldocs
Using alabaster theme
Using Python kernel-doc $ make SPHINXDIRS=peci pdfdocs
Error: pdflatex or latexmk required for PDF generation
make[2]: *** [Documentation/Makefile:64: pdfdocs] Error 1
make[1]: *** [/root/Makefile:1808: pdfdocs] Error 2
make: *** [Makefile:248: __sub-make] Error 2Which is the expected behavior.
--- Documentation/Makefile | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-)
Documentation/Makefile +4 -9
@@ -66,20 +66,15 @@ htmldocs mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkche --builddir="$(BUILDDIR)" --deny-vf=$(FONTS_CONF_DENY_VF) \ --theme=$(DOCS_THEME) --css=$(DOCS_CSS) --paper=$(PAPER) -# Special handling for pdfdocs -ifneq ($(shell which $(PDFLATEX) >/dev/null 2>&1; echo $$?),0) -pdfdocs: - $(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.) - @echo " SKIP Sphinx $@ target." -endif -htmldocs-redirects: $(srctree)/Documentation/.renames.txt - @tools/docs/gen-redirects.py --output $(BUILDDIR) < $< -endif # HAVE_SPHINX +endif # The following targets are independent of HAVE_SPHINX, and the rules should # work or silently pass without Sphinx. +htmldocs-redirects: $(srctree)/Documentation/.renames.txt + @tools/docs/gen-redirects.py --output $(BUILDDIR) < $< + refcheckdocs: $(Q)cd $(srctree);scripts/documentation-file-ref-check
Signature · 1 line
2.51.0
Re: [PATCH 2/2] docs: Makefile: avoid a warning when using without texlive
Quoted 30 lines · Mauro Carvalho Chehab
As reported by Randy, running make htmldocs on a machine without textlive now produce warnings:
$ make O=DOCS htmldocs ../Documentation/Makefile:70: warning: overriding recipe for target 'pdfdocs' ../Documentation/Makefile:61: warning: ignoring old recipe for target 'pdfdocs'That's because the code has now two definitions for pdfdocs in case $PDFLATEX command is not found. With the new script, such special case is not needed anymore, as the script checks it.
Drop the special case. Even after dropping it, on a machine without LaTeX, it will still produce an error as expected, as running:
$ ./tools/docs/sphinx-build-wrapper pdfdocs Error: pdflatex or latexmk required for PDF generationdoes the check. After applying the patch we have:
$ make SPHINXDIRS=peci htmldocs Using alabaster theme Using Python kernel-doc$ make SPHINXDIRS=peci pdfdocs Error: pdflatex or latexmk required for PDF generation make[2]: *** [Documentation/Makefile:64: pdfdocs] Error 1 make[1]: *** [/root/Makefile:1808: pdfdocs] Error 2 make: *** [Makefile:248: __sub-make] Error 2
Quoted 4 lines
Which is the expected behavior.
s/Link/Closes/
Quoted 1 line
Signed-off-by Mauro Carvalho Chehab <[email protected]>
Thanks.
Quoted 33 lines
--- Documentation/Makefile | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-)Documentation/Makefile +4
-9@@ -66,20 +66,15 @@ htmldocs mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkche --builddir="$(BUILDDIR)" --deny-vf=$(FONTS_CONF_DENY_VF) \ --theme=$(DOCS_THEME) --css=$(DOCS_CSS) --paper=$(PAPER) -# Special handling for pdfdocs -ifneq ($(shell which $(PDFLATEX) >/dev/null 2>&1; echo $$?),0) -pdfdocs: - $(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.) - @echo " SKIP Sphinx $@ target." -endif -htmldocs-redirects: $(srctree)/Documentation/.renames.txt - @tools/docs/gen-redirects.py --output $(BUILDDIR) < $< -endif # HAVE_SPHINX +endif # The following targets are independent of HAVE_SPHINX, and the rules should # work or silently pass without Sphinx. +htmldocs-redirects: $(srctree)/Documentation/.renames.txt + @tools/docs/gen-redirects.py --output $(BUILDDIR) < $< + refcheckdocs: $(Q)cd $(srctree);scripts/documentation-file-ref-check
Signature · 1 line
~Randy
Re: [PATCH 2/2] docs: Makefile: avoid a warning when using without texlive
In reply to Mauro Carvalho ChehabQuoted 24 lines · Mauro Carvalho Chehab
As reported by Randy, running make htmldocs on a machine without textlive now produce warnings:
$ make O=DOCS htmldocs ../Documentation/Makefile:70: warning: overriding recipe for target 'pdfdocs' ../Documentation/Makefile:61: warning: ignoring old recipe for target 'pdfdocs'That's because the code has now two definitions for pdfdocs in case $PDFLATEX command is not found. With the new script, such special case is not needed anymore, as the script checks it.
Drop the special case. Even after dropping it, on a machine without LaTeX, it will still produce an error as expected, as running:
$ ./tools/docs/sphinx-build-wrapper pdfdocs Error: pdflatex or latexmk required for PDF generationdoes the check. After applying the patch we have:
$ make SPHINXDIRS=peci htmldocs Using alabaster theme Using Python kernel-doc
Quoted 8 lines
$ make SPHINXDIRS=peci pdfdocs Error: pdflatex or latexmk required for PDF generation make[2]: *** [Documentation/Makefile:64: pdfdocs] Error 1 make[1]: *** [/root/Makefile:1808: pdfdocs] Error 2 make: *** [Makefile:248: __sub-make] Error 2Which is the expected behavior.
There seems to be a related issue.
At current "docs-mw", under build environments who don't have xelatex nor latexmk,
$ make SPHINXDIRS=peci latexdocs
completes without any issue.
In the resulting .../latex/peci directory, one can run
$ make PDFLATEX="latexmk -xelatex" LATEXOPTS="-interaction=batchmode -no-shell-escape"
and build peci.pdf.
At current "build-scripts", I get this:
$ make SPHINXDIRS=peci latexdocs
Error: pdflatex or latexmk required for PDF generation
make[2]: *** [Documentation/Makefile:68: latexdocs] Error 1
make[1]: *** [<srcdir>/Makefile:1806: latexdocs] Error 2
make: *** [Makefile:248: __sub-make] Error 2Patch 2/2 doesn't change the behavior.
This is yet another regression. Please teach sphinx-build-wrapper of the fact that "latexdocs" does not run those texlive commands. It is only the "pdfdocs" phase that will run them.
Regards,
Akira
Quoted 3 lines
Re: [PATCH 2/2] docs: Makefile: avoid a warning when using without texlive
Sorry, a quick follow-up.
Quoted 36 lines · Akira Yokosawa
Quoted 24 lines · Mauro Carvalho Chehab
As reported by Randy, running make htmldocs on a machine without textlive now produce warnings:
$ make O=DOCS htmldocs ../Documentation/Makefile:70: warning: overriding recipe for target 'pdfdocs' ../Documentation/Makefile:61: warning: ignoring old recipe for target 'pdfdocs'That's because the code has now two definitions for pdfdocs in case $PDFLATEX command is not found. With the new script, such special case is not needed anymore, as the script checks it.
Drop the special case. Even after dropping it, on a machine without LaTeX, it will still produce an error as expected, as running:
$ ./tools/docs/sphinx-build-wrapper pdfdocs Error: pdflatex or latexmk required for PDF generationdoes the check. After applying the patch we have:
$ make SPHINXDIRS=peci htmldocs Using alabaster theme Using Python kernel-docQuoted 8 lines
$ make SPHINXDIRS=peci pdfdocs Error: pdflatex or latexmk required for PDF generation make[2]: *** [Documentation/Makefile:64: pdfdocs] Error 1 make[1]: *** [/root/Makefile:1808: pdfdocs] Error 2 make: *** [Makefile:248: __sub-make] Error 2Which is the expected behavior.
There seems to be a related issue.
Quoted 7 lines
At current "docs-mw", under build environments who don't have xelatex nor latexmk,
$ make SPHINXDIRS=peci latexdocscompletes without any issue.
In the resulting .../latex/peci directory, one can run
I meant: .../peci/latex
Quoted 4 lines
$ make PDFLATEX="latexmk -xelatex" LATEXOPTS="-interaction=batchmode -no-shell-escape"and build peci.pdf.
I failed to mention, but of course you need to transfer/share said .../peci/latex/ to another build environment who has all the required packages for "pdfdocs".
I often use such heterogeneous combination of running "make latexdocs"
+ running make under each of .../$SPHINXDIRS/latex/ using another environment.
This way, you need only one set of working texlive packages for testing against various Sphinx's latex builder releases.
Quoted 9 lines
At current "build-scripts", I get this:
$ make SPHINXDIRS=peci latexdocs Error: pdflatex or latexmk required for PDF generation make[2]: *** [Documentation/Makefile:68: latexdocs] Error 1 make[1]: *** [<srcdir>/Makefile:1806: latexdocs] Error 2 make: *** [Makefile:248: __sub-make] Error 2
Quoted 6 lines
Patch 2/2 doesn't change the behavior.
This is yet another regression. Please teach sphinx-build-wrapper of the fact that "latexdocs" does not run those texlive commands. It is only the "pdfdocs" phase that will run them.
You see, "make latexdocs" is supposed to generate all the necessary files for building PDFs to be consumed by make + latexmk/xelatex. There is a clear boundary between "latexdocs" and "pdfdocs".
Thanks,
Akira
Quoted 6 lines
Regards,
AkiraQuoted 3 lines
Re: [PATCH 2/2] docs: Makefile: avoid a warning when using without texlive
Em Sat, 27 Sep 2025 18:12:19 +0900
Akira Yokosawa <[email protected]> escreveu:
Quoted 41 lines
Sorry, a quick follow-up.
Quoted 38 lines · Akira Yokosawa
Quoted 24 lines · Mauro Carvalho Chehab
As reported by Randy, running make htmldocs on a machine without textlive now produce warnings:
$ make O=DOCS htmldocs ../Documentation/Makefile:70: warning: overriding recipe for target 'pdfdocs' ../Documentation/Makefile:61: warning: ignoring old recipe for target 'pdfdocs'That's because the code has now two definitions for pdfdocs in case $PDFLATEX command is not found. With the new script, such special case is not needed anymore, as the script checks it.
Drop the special case. Even after dropping it, on a machine without LaTeX, it will still produce an error as expected, as running:
$ ./tools/docs/sphinx-build-wrapper pdfdocs Error: pdflatex or latexmk required for PDF generationdoes the check. After applying the patch we have:
$ make SPHINXDIRS=peci htmldocs Using alabaster theme Using Python kernel-docQuoted 8 lines
$ make SPHINXDIRS=peci pdfdocs Error: pdflatex or latexmk required for PDF generation make[2]: *** [Documentation/Makefile:64: pdfdocs] Error 1 make[1]: *** [/root/Makefile:1808: pdfdocs] Error 2 make: *** [Makefile:248: __sub-make] Error 2Which is the expected behavior.
There seems to be a related issue.
At current "docs-mw", under build environments who don't have xelatex nor latexmk,
Quoted 8 lines
Quoted 5 lines
$ make SPHINXDIRS=peci latexdocscompletes without any issue.
In the resulting .../latex/peci directory, one can run
I meant: .../peci/latex
True. This is an one-line fix:
@@ -650,7 +650,7 @@ class SphinxBuilder:
if not sphinxbuild and target != "mandocs":
sys.exit(f"Error: {self.sphinxbuild} not found in PATH.\n")
- if builder == "latex":
+ if target == "pdfdocs":
if not self.pdflatex_cmd and not self.latexmk_cmd:
sys.exit("Error: pdflatex or latexmk required for PDF generation")
With that:
$ make SPHINXDIRS=peci latexdocs Using alabaster theme Using Python kernel-doc WARNING: dot(1) not found, for better output quality install graphviz from https://www.graphviz.org
$ tree Documentation/output/
Documentation/output/
`-- peci
`-- latex
...
|-- Makefile
...
|-- peci.tex
...$ make SPHINXDIRS=peci pdfdocs Error: pdflatex or latexmk required for PDF generation make[2]: *** [Documentation/Makefile:64: pdfdocs] Error 1 make[1]: *** [/root/Makefile:1808: pdfdocs] Error 2 make: *** [Makefile:248: __sub-make] Error 2
$ (cd Documentation/output/peci/latex/; make) latexmk -pdf -dvi- -ps- 'peci.tex' make: latexmk: No such file or directory make: *** [Makefile:29: peci.pdf] Error 127
the original behavior is restored.
Quoted 27 lines
Quoted 4 lines
$ make PDFLATEX="latexmk -xelatex" LATEXOPTS="-interaction=batchmode -no-shell-escape"and build peci.pdf.
I failed to mention, but of course you need to transfer/share said .../peci/latex/ to another build environment who has all the required packages for "pdfdocs".
I often use such heterogeneous combination of running "make latexdocs"
+ running make under each of .../$SPHINXDIRS/latex/ using another environment.This way, you need only one set of working texlive packages for testing against various Sphinx's latex builder releases.
Quoted 11 lines
At current "build-scripts", I get this:
$ make SPHINXDIRS=peci latexdocs Error: pdflatex or latexmk required for PDF generation make[2]: *** [Documentation/Makefile:68: latexdocs] Error 1 make[1]: *** [<srcdir>/Makefile:1806: latexdocs] Error 2 make: *** [Makefile:248: __sub-make] Error 2Patch 2/2 doesn't change the behavior.
Quoted 8 lines
Quoted 4 lines
This is yet another regression. Please teach sphinx-build-wrapper of the fact that "latexdocs" does not run those texlive commands. It is only the "pdfdocs" phase that will run them.
You see, "make latexdocs" is supposed to generate all the necessary files for building PDFs to be consumed by make + latexmk/xelatex. There is a clear boundary between "latexdocs" and "pdfdocs".
True.
Such patch should address your usecase: it will allow building tex files on one machine and generate pdf on a different one.
Thanks,
Mauro
Jonathan Corbet
maintainerQuoted 8 lines · Mauro Carvalho Chehab
Hi Jon,
Another small series against build-script branch with fixes.
The first one removes bogus warnings when latex is not installed. The second one has a small fix to avoid writing *.pyc cache at the source dir.
Quoted 7 lines
Mauro Carvalho Chehab (2):
tools/docs/sphinx-build-wrapper: allow skipping sphinx-build step
docs:Makefile: avoid a warning when using without texliveDocumentation/Makefile | 13 ++++--------- tools/docs/sphinx-build-wrapper | 18 ++++++++++++------ 2 files changed, 16 insertions(+), 15 deletions(-)
I've kind of lost the plot with all of these patches but, in any case, this one doesn't apply here. If it's still needed, can I request a resend?
Thanks,
jon
Quoted 14 lines · Jonathan Corbet
Quoted 12 lines · Mauro Carvalho Chehab
Hi Jon,
Another small series against build-script branch with fixes.
The first one removes bogus warnings when latex is not installed. The second one has a small fix to avoid writing *.pyc cache at the source dir.
Mauro Carvalho Chehab (2):
tools/docs/sphinx-build-wrapper: allow skipping sphinx-build step
docs:Makefile: avoid a warning when using without texlive
Quoted 7 lines
Quoted 3 lines
Documentation/Makefile | 13 ++++--------- tools/docs/sphinx-build-wrapper | 18 ++++++++++++------ 2 files changed, 16 insertions(+), 15 deletions(-)I've kind of lost the plot with all of these patches but, in any case, this one doesn't apply here. If it's still needed, can I request a resend?
Sure. I'll rebase what I have, retest and send you on a single patch series.
Quoted 4 lines
Thanks,
jon
Signature · 2 lines
Thanks, Mauro