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

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

Em Wed, 03 Sep 2025 10:47:28 +0300
Jani Nikula <jani.nikula@intel.com> escreveu:

> On Tue, 02 Sep 2025, Laurent Pinchart <laurent.pinchart@ideasonboard.com> wrote:
> > I'm with Jon here, I wouldn't blindly override the Python interpreter
> > selected by the user. What we could however do is print a message if we
> > detect a version of Python that could improve performance, telling the
> > user they could switch.  
> 
> Just piling on here, totally agreed.
> 
> Don't surprise the user. Let the user be in control. If they choose a
> silly combo, let them. You know, they might be debugging the issues in
> that silly combo to begin with, and don't want to jump through hoops to
> work around tools that think they know better.
> 
> Letting the user know they're using a silly combo and suggesting better
> alternatives is a whole different matter.

The code can be changed to suggest a better alternative, and having an
optional argument to load the newest one automatically, but the issue
still remains:

if one has native python3.6, for instance, and he installed a newer one
to build htmldocs with:

	dnf install -y python3.11 # or zypper/apt-get/urpmi/... install python3.11

python3 will still be a soft link to python3.5, and all attempts to
build docs will fail.

With the approach I'm taken, Makefile will call sphinx-pre-install
and sphinx-build-wrapper. They both use a function that checks for
incompatible versions, re-running the code with one which works,
warning the user about that. So, on openSUSE leap, for instance, 
we have two official packages with Sphinx:

	$ grep PRETTY_NAME /etc/os-release 
	PRETTY_NAME="openSUSE Leap 15.6"

	$ zypper search sphinx |grep -E "python\S+\-Sphinx "
	   | python3-Sphinx                          | Python documentation generator                                              | package
	i+ | python311-Sphinx                        | Python documentation generator                                              | package


There, python3-Sphinx is too old:

	# sphinx-build --version
	sphinx-build 2.3.1

As docs minimal requirement is 3.4.3. Also, it is based on python3.6,
which is not compatible with the kernel Sphinx extensions.

Which the approach I took, once one installs python311-Sphinx like I did,
the build happens cleanly:

	$ make htmldocs
	# sphinx-pre-install, which checks is needed packages are installed
	Python 3.6.15 not supported. Changing to /usr/bin/python3.11
	# sphinx-build-wrapper, which calls Sphinx to build the docs
	Python version: 3.11.9
	Python 3.6.15 not supported. Changing to /usr/bin/python3.11
	Python version: 3.11.9
	Using alabaster theme
	Using Python kernel-doc
	...

but if we remove the switch logic:

        -print(f"Python {python_ver} not supported. Changing to {new_python_cmd}")
        -
        -try:
        -    os.execv(new_python_cmd, args)
        -except OSError as e:
        -    sys.exit(f"Failed to restart with {new_python_cmd}: {e}")
        -
	+print(f"Python {python_ver} not supported.")

The build will then fail:

	# make htmldocs
	Python 3.6.15 not supported.
	Python 3.6.15 not supported.
	Traceback (most recent call last):
	  File "/usr/bin/sphinx-build", line 5, in <module>
	    from sphinx.cmd.build import main
	ModuleNotFoundError: No module named 'sphinx'

because:

- python3.6 is not supported;
- sphinx-build is installed with python311-Sphinx, which also installed
  python311 package.

See, in this case, the user wanted docs build to use python3.11, as
it installed python311-Sphinx package from a distro official package.

Without the version-check logic, the only option would be for the user
to do:

	ln -sf python3 python3.11  # or something equivalent

-

Btw, the same type of packaging multiple versions of python and 
Sphinx is quite common on several distributions. This is not
an issue specific to openSUSE.

Also, notice that we're talking here about building docs with
distros that are using a 9+ years old python3, e.g.:

	- openSUSE Leap;
	- RHEL8-based distros;
	- other old LTS and EOL distros that have a too old Python 
	  versions.

Thanks,
Mauro