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

[Jonathan Corbet <corbet@lwn.net>]

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

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

But overriding the path is exactly what this would be doing.  It doesn't
seem right to say "we know better than you do" and circumvent the
configured path; the user may well have reasons for setting things up
the way they did.  Do you know of any other tool that behaves this way?

If we're really going to do it, I'd feel better if it had to be enabled
with a --fastest-python flag or some such.

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

Honestly, I'm not entirely convinced even here.  It really feels like
the kind of magic that may bite us one of these days.

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

...in which case, it seems to me we need to recommend that the path be
configured appropriately as well.

jon