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

[Jani Nikula <jani.nikula@intel.com>]

On Wed, 03 Sep 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> 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.

If the user wants to shoot themselves in the foot, let them.

> 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

-- 
Jani Nikula, Intel