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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <4d5757ff-5d63-4bb2-84e9-fb5618a696b3@infradead.org>
Date: Tue, 23 Sep 2025 22:05:14 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
 Jonathan Corbet <corbet@....net>,
 Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc: linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2 1/3] tools/docs: sphinx-build-wrapper: fix compat with
 recent Tumbleweed

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@...radead.org>
> Link: https://lore.kernel.org/all/883df949-0281-4a39-8745-bcdcce3a5594@infradead.org/
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
> ---
>   tools/docs/sphinx-build-wrapper | 25 ++++++++++++++++++++++---
>   1 file changed, 22 insertions(+), 3 deletions(-)

Works for me. Thanks.

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

-- 
~Randy