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

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

On Wed, Sep 03, 2025 at 04:57:15PM +0200, Mauro Carvalho Chehab wrote:
> 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.

This should fail. If you really insist you could print a message telling
the user there's another Python version on their system that may work,
but selecting it automatically isn't a good idea.

-- 
Regards,

Laurent Pinchart