Re: [PATCH v2 1/3] tools/docs: sphinx-build-wrapper: fix compat with recent Tumbleweed

[Randy Dunlap <rdunlap@infradead.org>]

Hi Mauro,


On 9/22/25 4:27 AM, Mauro Carvalho Chehab wrote:
> On recent versions of openSUSE Tumbleweed, sphinx-buildis is no longer
> a Python script, but something else. Such change is due to how
> it now handles alternatives:
> 
>      https://en.opensuse.org/openSUSE:Migrating_to_libalternatives_with_alts
> 
> The most common approach that distros use for alternatives is via
> symlinks:
> 
>      lrwxrwxrwx 1 root root 22 out 31  2024 /usr/bin/java -> /etc/alternatives/java
>      lrwxrwxrwx 1 root root 37 mar  5  2025 /etc/alternatives/java -> /usr/lib/jvm/java-21-openjdk/bin/java
> 
> With such approach, one can sun the script with either:
> 
>      <sphinx>
>      python3 <script>
> 
> However, openSUSE's implementation uses an ELF binary (/usr/bin/alts),
> which breaks the latter format.
> 
> It is needed to allow users to specify the Python version to be
> used while building docs, as some distros like Leap 15.x are
> shipped with:
> 
> - older, unsupported python3/python3-sphinx packages;
> - more modern python3xx/python3xx-sphinx packages that work
>    properly.
> 
> On such distros, building docs require running make with:
> 
>      make PYTHON3=python3.11 htmldocs
> 
> Heh, even on more moderen distros where python3-sphinx
> is supported, one may still want to use a newer package,
> for instance, due to performance issues, as:
> 
>      - with Python < 3.11, kernel-doc is 3 times slower;
>      - while building htmldocs with Python 3.13/Sphinx 8.x
>        takes about 3 minutes on a modern machine, using
>        Sphinx < 8.0 can take up to 16 minutes to build docs
>        (7.x are the worse ones and require lots of RAM).
> 
> So, even with not too old distros, one still may want to use
> for instance PYTHON3=python3.11.
> 
> To acommodate using PYTHON3 without breaking on Tumbleweed,
> add a workaround that will only use:
> 
>      $(PYTHON3) sphinx-build
> 
> if PYTHON3 env var is not default.
> 
> While here, drop the special check for venv, as, with venv,
> we can just call sphinx-build directly without any extra
> checks.
> 
> Reported-by: Randy Dunlap <rdunlap@infradead.org>
> Link: https://lore.kernel.org/all/883df949-0281-4a39-8745-bcdcce3a5594@infradead.org/
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>   tools/docs/sphinx-build-wrapper | 25 ++++++++++++++++++++++---
>   1 file changed, 22 insertions(+), 3 deletions(-)

Works for me. Thanks.

Tested-by: Randy Dunlap <rdunlap@infradead.org>

-- 
~Randy