[PATCH 0/3] some patches against build-script

[PATCH 0/3] some patches against build-script

[Mauro Carvalho Chehab]

Hi Jon,

This small patch series contain 3 minor fixes/cleanups for
sphinx-build-wrapper addressing some corner usecases.

Patch 1 was already submitted. It avoids 2 harmless warnings when
texlive is not installed.

Patch 2 fixes the checker for latexmk (PDFLATEX env) when texlive
is not installed.

Patch 3 restores the logic to store *.pyc files under builddir 
instead of sourcedir.

Mauro Carvalho Chehab (3):
  docs: Makefile: avoid a warning when using without texlive
  tools/docs: sphinx-build-wrapper: pdflatex is needed only for pdf
  docs: Makefile: use PYTHONPYCACHEPREFIX

 Documentation/Makefile          | 19 ++++++++-----------
 tools/docs/sphinx-build-wrapper |  2 +-
 2 files changed, 9 insertions(+), 12 deletions(-)

-- 
2.51.0

[PATCH 1/3] 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

[PATCH 2/3] tools/docs: sphinx-build-wrapper: pdflatex is needed only for pdf

[Mauro Carvalho Chehab]

Fix the logic which checks for pdflatex. Currently, it complains
for both pdfdocs and latexdocs, but for the latter, all it is
needed is Sphinx.

Reported-by: Akira Yokosawa <akiyks@gmail.com>
Closes: https://lore.kernel.org/linux-doc/cover.1758881658.git.mchehab+huawei@kernel.org/T/#ma81ff2e11b8579e5edc23e4381e464081ae668b7                                      Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/docs/sphinx-build-wrapper | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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

[PATCH 3/3] docs: Makefile: use PYTHONPYCACHEPREFIX

[Mauro Carvalho Chehab]

Previous cleanup patches ended dropping it when sphinx-build-wrapper
were added. Also, sphinx-pre-install can also generate caches.

So, re-add it for both.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/Makefile | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index f764604fa1ac..cf26d5332fb5 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -60,8 +60,10 @@ else # HAVE_SPHINX
 
 # Common documentation targets
 htmldocs mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
-	$(Q)@$(srctree)/tools/docs/sphinx-pre-install --version-check
-	+$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ \
+	$(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
+		@$(srctree)/tools/docs/sphinx-pre-install --version-check
+	+$(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
+		$(PYTHON3) $(BUILD_WRAPPER) $@ \
 		--sphinxdirs="$(SPHINXDIRS)" $(RUSTDOC) \
 		--builddir="$(BUILDDIR)" --deny-vf=$(FONTS_CONF_DENY_VF) \
 		--theme=$(DOCS_THEME) --css=$(DOCS_CSS) --paper=$(PAPER)
-- 
2.51.0

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

[Randy Dunlap]

On 9/29/25 1:53 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/

Maybe Closes: ?  Anyway:

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

Thanks.

> 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
>  
-- 
~Randy

Re: [PATCH 3/3] docs: Makefile: use PYTHONPYCACHEPREFIX

[Jonathan Corbet]

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

> Previous cleanup patches ended dropping it when sphinx-build-wrapper
> were added. Also, sphinx-pre-install can also generate caches.
>
> So, re-add it for both.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/Makefile | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index f764604fa1ac..cf26d5332fb5 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -60,8 +60,10 @@ else # HAVE_SPHINX
>  
>  # Common documentation targets
>  htmldocs mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
> -	$(Q)@$(srctree)/tools/docs/sphinx-pre-install --version-check
> -	+$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ \
> +	$(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
> +		@$(srctree)/tools/docs/sphinx-pre-install --version-check
> +	+$(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
> +		$(PYTHON3) $(BUILD_WRAPPER) $@ \

This causes an immediate build fail for me:

  /bin/sh: line 1: @./tools/docs/sphinx-pre-install: No such file or directory
  make[2]: *** [Documentation/Makefile:63: htmldocs] Error 127
  make[1]: *** [Makefile:1808: htmldocs] Error 2
  make: *** [Makefile:248: __sub-make] Error 2

jon

Re: [PATCH 3/3] docs: Makefile: use PYTHONPYCACHEPREFIX

[Mauro Carvalho Chehab]

On Wed, Oct 01, 2025 at 06:55:57AM -0600, Jonathan Corbet wrote:
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Previous cleanup patches ended dropping it when sphinx-build-wrapper
> > were added. Also, sphinx-pre-install can also generate caches.
> >
> > So, re-add it for both.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  Documentation/Makefile | 6 ++++--
> >  1 file changed, 4 insertions(+), 2 deletions(-)
> >
> > diff --git a/Documentation/Makefile b/Documentation/Makefile
> > index f764604fa1ac..cf26d5332fb5 100644
> > --- a/Documentation/Makefile
> > +++ b/Documentation/Makefile
> > @@ -60,8 +60,10 @@ else # HAVE_SPHINX
> >  
> >  # Common documentation targets
> >  htmldocs mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
> > -	$(Q)@$(srctree)/tools/docs/sphinx-pre-install --version-check
> > -	+$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ \
> > +	$(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
> > +		@$(srctree)/tools/docs/sphinx-pre-install --version-check

The problem is the "@" here...

> > +	+$(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
> > +		$(PYTHON3) $(BUILD_WRAPPER) $@ \
> 
> This causes an immediate build fail for me:
> 
>   /bin/sh: line 1: @./tools/docs/sphinx-pre-install: No such file or directory
>   make[2]: *** [Documentation/Makefile:63: htmldocs] Error 127
>   make[1]: *** [Makefile:1808: htmldocs] Error 2
>   make: *** [Makefile:248: __sub-make] Error 2

Fixed and will resend you a new version. This /3 series, plus a RFC
for kernel-doc are the only one pending.

I'll send the RFC in separate, and send a new version of this one.

> 
> jon

-- 
Thanks,
Mauro