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

[PATCH RFC 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/

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 | 33 +++++++++++++++++++++++---------
 tools/docs/sphinx-pre-install    |  2 +-
 2 files changed, 25 insertions(+), 10 deletions(-)

-- 
2.51.0

[PATCH RFC 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 RFC 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 | 31 ++++++++++++++++++++++++-------
 1 file changed, 24 insertions(+), 7 deletions(-)

diff --git a/tools/docs/lib/python_version.py b/tools/docs/lib/python_version.py
index 660bfe7d23fa..e2e9f9a3d421 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,12 @@ 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):
         """
         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 +115,33 @@ 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
+        # Check possible alternatives
+        if available_versions:
+            new_python_cmd = available_versions[0][1]
+        else:
+            new_python_cmd = None
+
         script_path = os.path.abspath(sys.argv[0])
         args = [new_python_cmd, script_path] + sys.argv[1:]
 
+        if show_alternatives:
+            print("Available Python versions:")
+            for _, cmd in available_versions:
+                print(f"  {cmd}")
+            print()
+
+        if bail_out:
+            sys.exit(f"Python {python_ver} not supported. Bailing out")
+
         print(f"Python {python_ver} not supported. Changing to {new_python_cmd}")
 
+        # Restart script using the newer version
         try:
             os.execv(new_python_cmd, args)
         except OSError as e:
-- 
2.51.0

[PATCH RFC 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 Available Python versions:
      /usr/bin/python3.11

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

It should be then up to the user to figure out a way to make
it work again.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/docs/sphinx-pre-install | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
index 663d4e2a3f57..ecd08e09bae9 100755
--- a/tools/docs/sphinx-pre-install
+++ b/tools/docs/sphinx-pre-install
@@ -1531,7 +1531,7 @@ def main():
 
     checker = SphinxDependencyChecker(args)
 
-    PythonVersion.check_python(MIN_PYTHON_VERSION)
+    PythonVersion.check_python(MIN_PYTHON_VERSION, show_alternatives=True)
     checker.check_needs()
 
 # Call main if not used as module
-- 
2.51.0