Re: [TECH TOPIC] Kernel documentation - update and future directions

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

Em Tue, 02 Sep 2025 09:15:49 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > To sum-up those discussions, I can propose a patchset for the next
> > merge window that would:
> >
> > 1. change kernel-doc exec to re-run using the latest available python
> >    version if version < 3.11, on a similar same way to what
> >    scripts-pre-install and scripts-build-wrapper does(*);  
> 
> I have to confess that I still feel some discomfort with this sort of
> "pick a better version" magic.  Should we really be overriding the
> search path that the user has set up?

The idea is not to override the search path: instead, to use it to
check if the user installed other /usr/bin/python3.* files (or on
some other part of PATH). Most distributions nowadays come with 
multiple python versions. I can't see a downside (*) of not using 
a newer version that the user had installed on his system and
has it on PATH.

For make htmldocs, if version is < 3.7 (or maybe 3.6), this is
mandatory: creating docs without that will fail. So, this is
actually a fallback measure in an attempt to save the day.
This is specially important for OpenSuse Leap, were we recommend
python311-sphinx package, which obviously require python 3.11
to run. The same applies for RHEL8-based distros and likely
old RHEL9 ones.

Now, for kernel-doc command line, checking against 3.11 is arguable,
as it runs slow, but works just fine with 3.7 to 3.10. 

Yet, trying to re-run costs about nothing, and make kernel-doc to
run 55% to 60% faster. IMO, it is worth. We can first check for
a PYTHON env to see if are there any overrides.

(*) The only possible issue is if the user installed python 3.11, but
    forgot to install python3.11-libs package, but it sounds easy enough
    to check if this is the case via a try/except logic.

Thanks,
Mauro