Break building docs on distros where python3==python3.6 or older
Subsystems (2)
cover Break building docs on distros where python3==python3.6 or older
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:
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/[email protected]/
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(-)
Signature · 1 line
2.51.0
RFC PATCH 1/3 tools/docs: python_version.py: drop a debug print
The version print at the lib was added for debugging purposes. Get rid of it.
--- tools/docs/lib/python_version.py | 2 -- 1 file changed, 2 deletions(-)
tools/docs/lib/python_version.py +0 -2
@@ -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)
Signature · 1 line
2.51.0
RFC PATCH 2/3 tools/docs: python_version: allow check for alternatives and bail out
In reply to Mauro Carvalho ChehabThe 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.
--- tools/docs/lib/python_version.py | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-)
tools/docs/lib/python_version.py +24 -7
@@ -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:
Signature · 1 line
2.51.0
RFC PATCH 3/3 tools/docs: sphinx-* break documentation bulds on openSUSE
In reply to Mauro Carvalho ChehabBefore 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 2It should be then up to the user to figure out a way to make it work again.
--- tools/docs/sphinx-pre-install | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
tools/docs/sphinx-pre-install +1 -1
@@ -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
Signature · 1 line
2.51.0