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

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

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.

> > 2. sphinx-build logic inside makefile, required for doc-specific targets:
> > 
> >    - If python < 3.7, doc builds fail;
> 
> Fine, python 3.7 is really old by now, if you actually have python3==3.7
> you probably have other problems anyway. I don't think we need to
> support that.

On our past discusions on linux-doc ML, we opted to support the latest
openSUSE LTS version (Leap).

> >    - If python3xx-Sphinx is installed, build only works if started using
> >      the right python3.xx exec
> 
> Yeah, but again, we can require python3-sphinx here.

See above. python311-Sphinx is OK, and it is a distro-installed package.

I can't see why we can't use to build the docs if the user explicitly
installed it.

> > Now, for (1) and (2), it should be possible to allow building docs even
> > if the distro requires Python < 3.7, providing extra packages for newer
> > Python, as almost all distros do. See, several distros require python
> > on their minimal install images, because it can be using during package
> > install. Removing the default python replacing by a new version may break
> > the system, as the newer version may not be backward-compatible.
> 
> Umm, no? I'm not sure there's a need to cater to truly ancient software
> in today's kernel build environment. Even debian *oldoldstable* has
> python3==3.9:
> https://packages.debian.org/bullseye/python3

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.

> > The best alternative seems to check if:
> > 
> > - python version is bellow the minimal supported version;
> > - there is a newer python binary at PATH;
> > - check if sphinx-build runs with the newest version.
> > 
> > If all those 3 conditions are met, build docs with a version that works,
> > printing a message to tell the user what Python binary was used.
> 
> I still disagree. The only predictable thing is to use "python3" and
> associated python3-xyz tools, and let things fail if those versions are
> too old.
> 
> Picking a random different version that will depend on the kernel
> version etc. is just going to introduce more moving parts and will
> eventually be painful.

When it becomes painful, we can drop it.

Anyway, I'll let it for Jon to decide.

-- 
Thanks,
Mauro