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

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

On Wed, Sep 03, 2025 at 09:37:36AM -0600, Jonathan Corbet wrote:
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > On Wed, Sep 03, 2025 at 05:11:12PM +0200, Johannes Berg wrote:
> >> On Wed, 2025-09-03 at 16:57 +0200, Mauro Carvalho Chehab wrote:
> >> > There are actually 3 different issues that depend on python version:
> >> > 
> >> > 1. sphinx-pre-install:
> >> > 
> >> >     This used to be a Perl script. The goal is to check if sphinx-build
> >> >     is installed and works, and identify missing dependencies.
> >> > 
> >> >     The problem is: if one installs python3xx-Sphinx, instead of
> >> >     python3-Sphinx, the script will fail, except if it first switches
> >> >     to python3.xx;
> >> 
> >> So let it fail. Fail is fine, at least it's a clear signal. The python3-
> >> Spinx package will anyway be a sort of meta-package that's basically
> >> empty and depends on a specific version.
> >
> > No, that's not the case. On Leap, python3-Sphinx uses python 3.6 and has
> > Sphinx version 2.3.x, which is too old.
> 
> That's Leap 15, presumably?

Yes. Leap 15.6 (the latest one)

> Given that 16 is due Real Soon Now, perhaps
> before any kernel with these changes is released, do we need to concern
> ourselves with that?

Not sure how it works on openSUSE, but on other LTS distros, people
usually wait at least for x.1 version (16.1) before migrating their
systems.

> > True, but at least one of the major LTS distros don't have it(*).
> >
> > We can review it after Leap is replaced for the next openSUSE release.
> >
> > (*) also, RHEL8 (and its derivated releases) suffer the same issues
> >      and they aren't EOL yet.
> >
> > For most of us, I doubt the fallback logic would ever be used.
> 
> CentOS 8 stream went EOL over a year ago.  How many people have systems
> stuck on RHEL 8 and are using them to do docs builds?
> 
> > When it becomes painful, we can drop it.
> >
> > Anyway, I'll let it for Jon to decide.
> 
> I still really don't think that adding that stuff is a good idea; our
> scripts should behave the way people expect them to and not go rooting
> around for alternative interpreters to feed themselves to.  I appreciate
> that you want to make things Just Work for people, that is a great goal,
> but this seems a step too far.

Ok, as I said, it is up to you to decide. I sent already a patch
series with the last patch making the build break with python 3.6:

    https://lore.kernel.org/linux-doc/cover.1756913837.git.mchehab+huawei@kernel.org/

Patches 1 and 2 should be OK to be merged. Patch 3 is the one that
will break for Leap15/RHEL8 and other distros where python 3.6 is
required for the distro default (and typically mandatory) python3
package.

Feel free to apply it or not as you wish.

Thanks,
Mauro