[PATCH 0/2] some fixes for docs Makefile

[PATCH 0/2] some fixes for docs Makefile

[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

 Documentation/Makefile          | 13 ++++---------
 tools/docs/sphinx-build-wrapper | 18 ++++++++++++------
 2 files changed, 16 insertions(+), 15 deletions(-)

-- 
2.51.0

[PATCH 1/2] tools/docs/sphinx-build-wrapper: allow skipping sphinx-build step

[Mauro Carvalho Chehab]

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.

Requested-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/linux-doc/5031e0c4-f17e-41b8-8955-959989e797f2@gmail.com/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/docs/sphinx-build-wrapper | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 98c4db5b7c47..cce985dced00 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -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()
-- 
2.51.0

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

[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 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.

Reported-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/linux-doc/e7c29532-71de-496b-a89f-743cef28736e@infradead.org/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/Makefile | 13 ++++---------
 1 file changed, 4 insertions(+), 9 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index c60db1038c9c..f764604fa1ac 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -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
 
-- 
2.51.0

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

[Randy Dunlap]

On 9/26/25 3:16 AM, 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.
> 
> Reported-by: Randy Dunlap <rdunlap@infradead.org>
> Link: https://lore.kernel.org/linux-doc/e7c29532-71de-496b-a89f-743cef28736e@infradead.org/

s/Link/Closes/

> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>   Documentation/Makefile | 13 ++++---------
>   1 file changed, 4 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index c60db1038c9c..f764604fa1ac 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -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
>   

-- 
~Randy

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

[Akira Yokosawa]

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

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

Regards,
Akira

> Reported-by: Randy Dunlap <rdunlap@infradead.org>
> Link: https://lore.kernel.org/linux-doc/e7c29532-71de-496b-a89f-743cef28736e@infradead.org/
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

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

[Akira Yokosawa]

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

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

Thanks,
Akira

> Regards,
> Akira
> 
>> Reported-by: Randy Dunlap <rdunlap@infradead.org>
>> Link: https://lore.kernel.org/linux-doc/e7c29532-71de-496b-a89f-743cef28736e@infradead.org/
>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

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

[Mauro Carvalho Chehab]

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

Re: [PATCH 0/2] some fixes for docs Makefile

[Jonathan Corbet]

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

> 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(-)

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

Re: [PATCH 0/2] some fixes for docs Makefile

[Mauro Carvalho Chehab]

On Wed, Oct 01, 2025 at 06:58:41AM -0600, Jonathan Corbet wrote:
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > 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(-)
> 
> 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.

> 
> Thanks,
> 
> jon

-- 
Thanks,
Mauro