Re: [PATCH] Makefile: Let kernel-doc.py use PYTHON3 override

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

Em Mon, 3 Nov 2025 11:00:51 -0800
Randy Dunlap <rdunlap@infradead.org> escreveu:

> Hi,
> 
> On 11/3/25 10:56 AM, Nathan Chancellor wrote:
> > On Mon, Nov 03, 2025 at 01:14:19PM +0100, Jean Delvare wrote:  
> >> It is possible to force a specific version of python to be used when
> >> building the kernel by passing PYTHON3= on the make command line.
> >> However kernel-doc.py is currently called with python3 hard-coded and
> >> thus ignores this setting.
> >>
> >> Use PYTHON3 to call kernel-doc.py so that the desired version of
> >> python is used.
> >>
> >> Signed-off-by: Jean Delvare <jdelvare@suse.de>  
> > 
> > I see one use of KERNELDOC in tools/docs/sphinx-build-wrapper that would
> > appear to break with this change? Does it matter? I am not familiar with
> > the docs build. Otherwise, this seems like the correct thing to do.  
> 
> I think there has been some discussion of these matters on the linux-doc
> mailing list (adding it here).

Yes. The way the current building system works, after the discussions,
is that:

1. Makefile runs sphinx-build-wrapper, which is a python script, using
   this target:

    htmldocs mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
        $(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. sphinx-build-wrapper will run sphinx-build with the same python
   version it was called;
3. Sphinx kerneldoc.py extension will directly call kernel-doc
   classes, meaning that it will use the same python version as
   sphinx-build. There, it will use KERNELDOC var *only* to check if
   it ends with ".py", as there is (still) a fallback code there to allow
   running a different script via fork.

On other words, if one wants to run a different python version, it has
to do:

	make PYTHON3=/usr/bin/python-3.11 htmldocs

This should work for doc builds.

Please notice, however, that kERNEL_DOC env var is also called at some
DRM makefiles. Perhaps the issue you're getting is there.

Regards,
Mauro

> 
> >> ---
> >>  Makefile |    2 +-
> >>  1 file changed, 1 insertion(+), 1 deletion(-)
> >>
> >> --- linux-6.17.orig/Makefile
> >> +++ linux-6.17/Makefile
> >> @@ -460,7 +460,7 @@ HOSTPKG_CONFIG	= pkg-config
> >>  
> >>  # the KERNELDOC macro needs to be exported, as scripts/Makefile.build
> >>  # has a logic to call it
> >> -KERNELDOC       = $(srctree)/scripts/kernel-doc.py
> >> +KERNELDOC       = $(PYTHON3) $(srctree)/scripts/kernel-doc.py

This is not the right place to add it, as it may break the Sphinx 
extension.

> >>  export KERNELDOC
> >>  
> >>  KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
> >>
> >>
> >> -- 
> >> Jean Delvare
> >> SUSE L3 Support  
> >   
>