Re: [PATCH 2/2] docs: Makefile: avoid a warning when using without texlive

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Sat, 27 Sep 2025 18:12:19 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> Sorry, a quick follow-up.
> 
> On Sat, 27 Sep 2025 16:35:08 +0900, Akira Yokosawa wrote:
> > On Fri, 26 Sep 2025 12:16:19 +0200, Mauro Carvalho Chehab wrote:  
> >> 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 generation
> >>
> >> does 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
> >>
> >> Which 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  
> 
>      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.

> > 
> >     $ 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.
> 
> > 
> > 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
> > 
> > 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".

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