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

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

On Tue, Sep 02, 2025 at 07:19:29PM +0200, Mauro Carvalho Chehab wrote:
> Em Tue, 02 Sep 2025 09:15:49 -0600 Jonathan Corbet 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.

I'm with Jon here, I wouldn't blindly override the Python interpreter
selected by the user. What we could however do is print a message if we
detect a version of Python that could improve performance, telling the
user they could switch.

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

-- 
Regards,

Laurent Pinchart