Re: linux-next: Tree for Sep 19 (make htmldocs problem)

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

Em Sun, 21 Sep 2025 22:32:50 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Em Sun, 21 Sep 2025 13:27:48 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
> > Randy Dunlap <rdunlap@infradead.org> writes:
> > 
> > > lrwxrwxrwx 1 root root 4 Sep 11 01:42 /usr/bin/sphinx-build -> alts*
> > >
> > > $ file  /usr/bin/alts
> > > /usr/bin/alts: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 4.3.0, BuildID[sha1]=17681640c9985eb36ae6d9eca0f08159509386c4, stripped  
> 
> Such setup looks weird on my eyes... why is it pointing to some other
> exec?
> 
> > 
> > That is clearly the problem, when combined with this code in
> > sphinx-build-wrapper:
> > 
> > >             if self.venv:
> > >                 cmd = ["python"]
> > >             else:
> > >                 cmd = [sys.executable,]
> 
> It ended that an extra comma is here, added on one of my final
> rebases. I noticed it already and one of the patches I sent during
> the weekend fixes it.
> 
> > > 
> > >             cmd += [sphinx_build]  
> > 
> > Mauro, what is the reason for explicitly interposing the interpreter
> > there rather than just invoking the sphinx-build binary directly?  It
> > seems like we could take that out and make this problem go away?
> 
> I added it to ensure that it would be using exactly the same python
> version that was called via makefile, which is called with:
> 
> 	Documentation/Makefile: +$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ \
> 
> See, the other alternatives:
> 
> 	# This may not run the same Python version, as it doesn't
> 	# take PYTHON3 var into account
> 	cmd = [sphinx_build]

This breaks when one is using PYTHON3 env with something different
than python3...
> 
> and:
> 	# This would require some extra logic for it to work 
> 	# when calling shinx-build-wrapper directly from command line
> 	cmd = [PYTHON3, sphinx_build]

Heh, this would require a change at Kernel's main Makefile,
and will likely break Kernel compilation, or an explicit check
if PYTHON3 != "python3". See suggested fix below.

Thanks,
Mauro

---

[PATCH] [RFC] tools/docs: sphinx-build-wrapper: accept non-python sphinx-build

At least on some environments, sphinx-build is an ELF executable,
with some weird alternate logic. This causes the logic which
honours PYTHON3 env var to break.

Change the logic to pick PYTHON3 directly from the environment,
using it only when explicitly set with a value different than python3.13.

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>

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 1f9c66ab33fe..ccffc51d9caf 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -274,8 +274,10 @@ class SphinxBuilder:
 
             if self.venv:
                 cmd = ["python"]
+            elif self.env.get("PYTHON3", "python3") != "python3":
+                cmd = [self.env["PYTHON3"]]
             else:
-                cmd = [sys.executable]
+                cmd = []
 
             cmd += [sphinx_build]
             cmd += [f"-j{n_jobs}"]