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

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

On Wed, Sep 03, 2025 at 12:54:04PM +0200, Johannes Berg wrote:
> On Wed, 2025-09-03 at 12:45 +0200, Johannes Berg wrote:
> > 
> > I don't follow. If this setup breaks the build then that's good, I'll
> > fix the env. If the build does magic inside and sort of ignores $PATH,
> > that's bad.
> 
> Or maybe it's not ignoring $PATH, but rather picking the "best"
> python3.xy binary from $PATH - still that's annoying because you'd have
> to control which ones are there and/or know which ones it might pick.
> 
> Far more predictable and usable to just use "python3" and print a
> message saying you might want to use a better version if you think it's
> too slow.

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;

2. sphinx-build logic inside makefile, required for doc-specific targets:

   - If python < 3.7, doc builds fail;
   - If python3xx-Sphinx is installed, build only works if started using
     the right python3.xx exec

3. kernel-doc via command line. Python >=3.6 and <= 3.11 works. It is
   just 60% slower.

For (3), I agree with you: let it run at the slow way, printing a warning;
eventually suggesting a newer version and, as Jon suggested, added a
command line like --newest-python that could optionally pick the fastest
version.

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.

So, what distros do, instead, to ensure backward-compatibility is to
provide multpile Python versions (together with python libraries).

The htmldocs/pdfdocs/... targets must support it somehow.

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.

Thanks,
Mauro