[PATCH v2 0/3] Break building docs on distros where python3==python3.6 or older

[PATCH v2 0/3] Break building docs on distros where python3==python3.6 or older

[Mauro Carvalho Chehab]

Add two patches improving python_version logic, adding two extra
optional arguments: show_alternatives and bail_out.

The third patch changes the build behavior in a way that distros
shipped with Python 3.6 like openSUSE Leap, RHEL8 and others will
break.

Personally, I'm against such patch, but based on some discussions at:

    https://lore.kernel.org/linux-doc/n4qixsp23dccgz6mtrmd2xumcngtphkbywjnxkrqpnuf2dbu2p@2sj44sbyga4j/T/#t

Several developers voiced that the best is to break the build.
So, I'll let up to the docs maintainer to decide weather or not
apply the final patch or replace by something that would avoid
such breakage.

This series is on top of the sphinx-build-wrapper patch:
    https://lore.kernel.org/linux-doc/cover.1756740314.git.mchehab+huawei@kernel.org/

---

v2:
- I forgot to merge some hunks at the last patch;
- I ended modifying the logic: it now provides a hint at the broken
  distros, showing how to call sphinx-build-wrapper directly to
  override the python3 version.

Mauro Carvalho Chehab (3):
  tools/docs: python_version.py: drop a debug print
  tools/docs: python_version: allow check for alternatives and bail out
  tools/docs: sphinx-* break documentation bulds on openSUSE

 tools/docs/lib/python_version.py | 45 +++++++++++++++++++++++++-------
 tools/docs/sphinx-build-wrapper  |  3 ++-
 tools/docs/sphinx-pre-install    |  3 ++-
 3 files changed, 39 insertions(+), 12 deletions(-)

-- 
2.51.0

[PATCH v2 1/3] tools/docs: python_version.py: drop a debug print

[Mauro Carvalho Chehab]

The version print at the lib was added for debugging purposes.
Get rid of it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/docs/lib/python_version.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/tools/docs/lib/python_version.py b/tools/docs/lib/python_version.py
index 0519d524e547..660bfe7d23fa 100644
--- a/tools/docs/lib/python_version.py
+++ b/tools/docs/lib/python_version.py
@@ -109,8 +109,6 @@ class PythonVersion:
         cur_ver = sys.version_info[:3]
         if cur_ver >= min_version:
             ver = PythonVersion.ver_str(cur_ver)
-            print(f"Python version: {ver}")
-
             return
 
         python_ver = PythonVersion.ver_str(cur_ver)
-- 
2.51.0

[PATCH v2 2/3] tools/docs: python_version: allow check for alternatives and bail out

[Mauro Carvalho Chehab]

The caller script may not want an automatic execution of the new
version. Add two parameters to allow showing alternatives and to
bail out if version is incompatible.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/docs/lib/python_version.py | 43 ++++++++++++++++++++++++++------
 1 file changed, 35 insertions(+), 8 deletions(-)

diff --git a/tools/docs/lib/python_version.py b/tools/docs/lib/python_version.py
index 660bfe7d23fa..a9fda2470a26 100644
--- a/tools/docs/lib/python_version.py
+++ b/tools/docs/lib/python_version.py
@@ -85,10 +85,12 @@ class PythonVersion:
         may need to update it one day, hopefully on a distant future.
         """
         patterns = [
-            "python3.[0-9]",
             "python3.[0-9][0-9]",
+            "python3.[0-9]",
         ]
 
+        python_cmd = []
+
         # Seek for a python binary newer than min_version
         for path in os.getenv("PATH", "").split(":"):
             for pattern in patterns:
@@ -96,12 +98,13 @@ class PythonVersion:
                     if os.path.isfile(cmd) and os.access(cmd, os.X_OK):
                         version = PythonVersion.get_python_version(cmd)
                         if version >= min_version:
-                            return cmd
+                            python_cmd.append((version, cmd))
 
-        return None
+        return sorted(python_cmd, reverse=True)
 
     @staticmethod
-    def check_python(min_version):
+    def check_python(min_version, show_alternatives=False, bail_out=False,
+                     success_on_error=False):
         """
         Check if the current python binary satisfies our minimal requirement
         for Sphinx build. If not, re-run with a newer version if found.
@@ -113,18 +116,42 @@ class PythonVersion:
 
         python_ver = PythonVersion.ver_str(cur_ver)
 
-        new_python_cmd = PythonVersion.find_python(min_version)
-        if not new_python_cmd:
+        available_versions = PythonVersion.find_python(min_version)
+        if not available_versions:
             print(f"ERROR: Python version {python_ver} is not spported anymore\n")
             print("       Can't find a new version. This script may fail")
             return
 
-        # Restart script using the newer version
         script_path = os.path.abspath(sys.argv[0])
-        args = [new_python_cmd, script_path] + sys.argv[1:]
+
+        # Check possible alternatives
+        if available_versions:
+            new_python_cmd = available_versions[0][1]
+        else:
+            new_python_cmd = None
+
+        if show_alternatives:
+            print("You could run, instead:")
+            for _, cmd in available_versions:
+                args = [cmd, script_path] + sys.argv[1:]
+
+                cmd_str = " ".join(args)
+                print(f"  {cmd_str}")
+            print()
+
+        if bail_out:
+            msg = f"Python {python_ver} not supported. Bailing out"
+            if success_on_error:
+                print(msg, file=sys.stderr)
+                sys.exit(0)
+            else:
+                sys.exit(msg)
 
         print(f"Python {python_ver} not supported. Changing to {new_python_cmd}")
 
+        # Restart script using the newer version
+        args = [new_python_cmd, script_path] + sys.argv[1:]
+
         try:
             os.execv(new_python_cmd, args)
         except OSError as e:
-- 
2.51.0

[PATCH v2 3/3] tools/docs: sphinx-* break documentation bulds on openSUSE

[Mauro Carvalho Chehab]

Before this patch, building htmldocs on opensuseLEAP works
fine:

    # make htmldocs
    Available Python versions:
      /usr/bin/python3.11

    Python 3.6.15 not supported. Changing to /usr/bin/python3.11
    Python 3.6.15 not supported. Changing to /usr/bin/python3.11
    Using alabaster theme
    Using Python kernel-doc

    ...

As the logic detects that Python 3.6 is too old and recommends
intalling python311-Sphinx. If installed, documentation builds
work like a charm.

Yet, some develpers complained that running python3.11 instead
of python3 should not happen. So, let's break the build to make
them happier:

    $ make htmldocs
    Python 3.6.15 not supported. Bailing out
    You could run, instead:
      /usr/bin/python3.11 /root/tools/docs/sphinx-build-wrapper htmldocs --sphinxdirs=. --conf=conf.py --theme= --css= --paper=

    Python 3.6.15 not supported. Bailing out
    make[2]: *** [Documentation/Makefile:75: htmldocs] Error 1
    make[1]: *** [/root/Makefile:1806: htmldocs] Error 2
    make: *** [Makefile:248: __sub-make] Error 2

It should be noticed that:

1. after this change, sphinx-pre-install needs to be called
   by hand:

    $ /usr/bin/python3.11 tools/docs/sphinx-pre-install
    Detected OS: openSUSE Leap 15.6.
    Sphinx version: 7.2.6

    All optional dependencies are met.
    Needed package dependencies are met.

2. sphinx-build-wrapper will auto-detect python3.11 and
   suggest a way to build the docs using the parameters passed
   via make variables. In this specific example:

   /usr/bin/python3.11 /root/tools/docs/sphinx-build-wrapper htmldocs --sphinxdirs=. --conf=conf.py --theme= --css= --paper=

3. As this needs to be executed outside docs Makefile, it won't run
   the validation check scripts nor build Rust documentation if
   enabled, as the extra scripts are part of the docs Makefile.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/docs/sphinx-build-wrapper | 3 ++-
 tools/docs/sphinx-pre-install   | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 932b1b675274..48e6e0a76aeb 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -719,7 +719,8 @@ def main():
 
     args = parser.parse_args()
 
-    PythonVersion.check_python(MIN_PYTHON_VERSION)
+    PythonVersion.check_python(MIN_PYTHON_VERSION, show_alternatives=True,
+                               bail_out=True)
 
     builder = SphinxBuilder(venv=args.venv, verbose=args.verbose,
                             n_jobs=args.jobs, interactive=args.interactive)
diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
index 663d4e2a3f57..698989584b6a 100755
--- a/tools/docs/sphinx-pre-install
+++ b/tools/docs/sphinx-pre-install
@@ -1531,7 +1531,8 @@ def main():
 
     checker = SphinxDependencyChecker(args)
 
-    PythonVersion.check_python(MIN_PYTHON_VERSION)
+    PythonVersion.check_python(MIN_PYTHON_VERSION,
+                               bail_out=True, success_on_error=True)
     checker.check_needs()
 
 # Call main if not used as module
-- 
2.51.0

Re: [PATCH v2 3/3] tools/docs: sphinx-* break documentation bulds on openSUSE

[Matthew Wilcox]

On Wed, Sep 03, 2025 at 06:24:16PM +0200, Mauro Carvalho Chehab wrote:
> Before this patch, building htmldocs on opensuseLEAP works
> fine:
> 
>     # make htmldocs
>     Available Python versions:
>       /usr/bin/python3.11
> 
>     Python 3.6.15 not supported. Changing to /usr/bin/python3.11
>     Python 3.6.15 not supported. Changing to /usr/bin/python3.11

[...]

> 1. after this change, sphinx-pre-install needs to be called
>    by hand:
> 
>     $ /usr/bin/python3.11 tools/docs/sphinx-pre-install
>     Detected OS: openSUSE Leap 15.6.
>     Sphinx version: 7.2.6

I thought the preferred option was to be able to specify:

PYTHON=/usr/bin/python3.11 make htmldocs

or even make htmldocs PYTHON=/usr/bin/python3.11

like being able to specify CC, LD or AWK.

Re: [PATCH v2 3/3] tools/docs: sphinx-* break documentation bulds on openSUSE

[Randy Dunlap]

On 9/3/25 9:24 AM, Mauro Carvalho Chehab wrote:
> Before this patch, building htmldocs on opensuseLEAP works
> fine:
> 
>     # make htmldocs
>     Available Python versions:
>       /usr/bin/python3.11
> 
>     Python 3.6.15 not supported. Changing to /usr/bin/python3.11
>     Python 3.6.15 not supported. Changing to /usr/bin/python3.11
>     Using alabaster theme
>     Using Python kernel-doc
> 
>     ...
> 
> As the logic detects that Python 3.6 is too old and recommends
> intalling python311-Sphinx. If installed, documentation builds
> work like a charm.
> 
> Yet, some develpers complained that running python3.11 instead
> of python3 should not happen. So, let's break the build to make
> them happier:
> 
>     $ make htmldocs
>     Python 3.6.15 not supported. Bailing out
>     You could run, instead:
>       /usr/bin/python3.11 /root/tools/docs/sphinx-build-wrapper htmldocs --sphinxdirs=. --conf=conf.py --theme= --css= --paper=

                            /root
??

> 
>     Python 3.6.15 not supported. Bailing out
>     make[2]: *** [Documentation/Makefile:75: htmldocs] Error 1
>     make[1]: *** [/root/Makefile:1806: htmldocs] Error 2
>     make: *** [Makefile:248: __sub-make] Error 2
> 
> It should be noticed that:
> 
> 1. after this change, sphinx-pre-install needs to be called
>    by hand:
> 
>     $ /usr/bin/python3.11 tools/docs/sphinx-pre-install
>     Detected OS: openSUSE Leap 15.6.
>     Sphinx version: 7.2.6
> 
>     All optional dependencies are met.
>     Needed package dependencies are met.
> 
> 2. sphinx-build-wrapper will auto-detect python3.11 and
>    suggest a way to build the docs using the parameters passed
>    via make variables. In this specific example:
> 
>    /usr/bin/python3.11 /root/tools/docs/sphinx-build-wrapper htmldocs --sphinxdirs=. --conf=conf.py --theme= --css= --paper=

ditto.

> 
> 3. As this needs to be executed outside docs Makefile, it won't run
>    the validation check scripts nor build Rust documentation if
>    enabled, as the extra scripts are part of the docs Makefile.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  tools/docs/sphinx-build-wrapper | 3 ++-
>  tools/docs/sphinx-pre-install   | 3 ++-
>  2 files changed, 4 insertions(+), 2 deletions(-)
> 
> diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
> index 932b1b675274..48e6e0a76aeb 100755
> --- a/tools/docs/sphinx-build-wrapper
> +++ b/tools/docs/sphinx-build-wrapper
> @@ -719,7 +719,8 @@ def main():
>  
>      args = parser.parse_args()
>  
> -    PythonVersion.check_python(MIN_PYTHON_VERSION)
> +    PythonVersion.check_python(MIN_PYTHON_VERSION, show_alternatives=True,
> +                               bail_out=True)
>  
>      builder = SphinxBuilder(venv=args.venv, verbose=args.verbose,
>                              n_jobs=args.jobs, interactive=args.interactive)
> diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
> index 663d4e2a3f57..698989584b6a 100755
> --- a/tools/docs/sphinx-pre-install
> +++ b/tools/docs/sphinx-pre-install
> @@ -1531,7 +1531,8 @@ def main():
>  
>      checker = SphinxDependencyChecker(args)
>  
> -    PythonVersion.check_python(MIN_PYTHON_VERSION)
> +    PythonVersion.check_python(MIN_PYTHON_VERSION,
> +                               bail_out=True, success_on_error=True)
>      checker.check_needs()
>  
>  # Call main if not used as module

-- 
~Randy

Re: [PATCH v2 3/3] tools/docs: sphinx-* break documentation bulds on openSUSE

[Mauro Carvalho Chehab]

Em Wed, 3 Sep 2025 10:41:12 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:

> On 9/3/25 9:24 AM, Mauro Carvalho Chehab wrote:
> > Before this patch, building htmldocs on opensuseLEAP works
> > fine:
> > 
> >     # make htmldocs
> >     Available Python versions:
> >       /usr/bin/python3.11
> > 
> >     Python 3.6.15 not supported. Changing to /usr/bin/python3.11
> >     Python 3.6.15 not supported. Changing to /usr/bin/python3.11
> >     Using alabaster theme
> >     Using Python kernel-doc
> > 
> >     ...
> > 
> > As the logic detects that Python 3.6 is too old and recommends
> > intalling python311-Sphinx. If installed, documentation builds
> > work like a charm.
> > 
> > Yet, some develpers complained that running python3.11 instead
> > of python3 should not happen. So, let's break the build to make
> > them happier:
> > 
> >     $ make htmldocs
> >     Python 3.6.15 not supported. Bailing out
> >     You could run, instead:
> >       /usr/bin/python3.11 /root/tools/docs/sphinx-build-wrapper htmldocs --sphinxdirs=. --conf=conf.py --theme= --css= --paper=  
> 
>                             /root
> ??

heh, you got me :-D

I ran it on an opensuse Leap container, created only to test builds.
I didn't care enough to create any user on such test containers, just
running everything there as root via lxc-attach, as, at the worse case
scenario, I can just re-run the script to re-create it.


Thanks,
Mauro

Re: [PATCH v2 3/3] tools/docs: sphinx-* break documentation bulds on openSUSE

[Mauro Carvalho Chehab]

Em Wed, 3 Sep 2025 18:38:37 +0100
Matthew Wilcox <willy@infradead.org> escreveu:

> On Wed, Sep 03, 2025 at 06:24:16PM +0200, Mauro Carvalho Chehab wrote:
> > Before this patch, building htmldocs on opensuseLEAP works
> > fine:
> > 
> >     # make htmldocs
> >     Available Python versions:
> >       /usr/bin/python3.11
> > 
> >     Python 3.6.15 not supported. Changing to /usr/bin/python3.11
> >     Python 3.6.15 not supported. Changing to /usr/bin/python3.11  
> 
> [...]
> 
> > 1. after this change, sphinx-pre-install needs to be called
> >    by hand:
> > 
> >     $ /usr/bin/python3.11 tools/docs/sphinx-pre-install
> >     Detected OS: openSUSE Leap 15.6.
> >     Sphinx version: 7.2.6  
> 
> I thought the preferred option was to be able to specify:
> 
> PYTHON=/usr/bin/python3.11 make htmldocs
> 
> or even make htmldocs PYTHON=/usr/bin/python3.11
> 
> like being able to specify CC, LD or AWK.

This could be an option, but it is still half-broken - or at least
implementing it is not trivial - as spinx-pre-install is the
script which recommends what packages are needed on openSUSE Leap.
and on RHEL8 (and based) distros.

Internally, it needs to run sphinx-build --version to check if
Sphinx version is compatible with the build. So, adding support
for a PYTHON env is still half-broken after this series.

Thanks,
Mauro