Break building docs on distros where python3==python3.6 or older
Subsystems (3)
v2 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]/
---
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(-)
Signature · 1 line
2.51.0
PATCH v2 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
PATCH v2 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 | 43 ++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 8 deletions(-)
tools/docs/lib/python_version.py +35 -8
@@ -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:
Signature · 1 line
2.51.0
PATCH v2 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
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 2It 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.
--- tools/docs/sphinx-build-wrapper | 3 ++- tools/docs/sphinx-pre-install | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-)
tools/docs/sphinx-build-wrapper +2 -1
@@ -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)
tools/docs/sphinx-pre-install +2 -1
@@ -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
Signature · 1 line
2.51.0
Re: [PATCH v2 3/3] tools/docs: sphinx-* break documentation bulds on openSUSE
Quoted 9 lines · Mauro Carvalho Chehab
Before this patch, building htmldocs on opensuseLEAP works fine:
# make htmldocs Available Python versions: /usr/bin/python3.11Python 3.6.15 not supported. Changing to
/usr/bin/python3.11Python 3.6.15 not supported. Changing to/usr/bin/python3.11
[...]
Quoted 6 lines
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
Em Wed, 3 Sep 2025 18:38:37 +0100
Matthew Wilcox <[email protected]> escreveu:
Quoted 20 lines · Mauro Carvalho Chehab
Quoted 9 lines
Before this patch, building htmldocs on opensuseLEAP works fine:
# make htmldocs Available Python versions: /usr/bin/python3.11Python 3.6.15 not supported. Changing to
/usr/bin/python3.11Python 3.6.15 not supported. Changing to/usr/bin/python3.11[...]
Quoted 6 lines
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
Quoted 7 lines
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
Randy Dunlap
reviewerRe: [PATCH v2 3/3] tools/docs: sphinx-* break documentation bulds on openSUSE
In reply to Mauro Carvalho ChehabQuoted 18 lines · Mauro Carvalho Chehab
Before this patch, building htmldocs on opensuseLEAP works fine:
# make htmldocs Available Python versions: /usr/bin/python3.11Python 3.6.15 not supported. Changing to
/usr/bin/python3.11Python 3.6.15 not supported. Changing to/usr/bin/python3.11Using 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.
Quoted 8 lines
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
??
Quoted 15 lines
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 2It 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
Quoted 8 lines
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.
Quoted 39 lines
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 docsMakefile.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- tools/docs/sphinx-build-wrapper | 3 ++- tools/docs/sphinx-pre-install | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-)tools/docs/sphinx-build-wrapper +2
-1@@ -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)tools/docs/sphinx-pre-install +2
-1@@ -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
Signature · 1 line
~Randy
Re: [PATCH v2 3/3] tools/docs: sphinx-* break documentation bulds on openSUSE
Em Wed, 3 Sep 2025 10:41:12 -0700
Randy Dunlap <[email protected]> escreveu:
Quoted 23 lines · Mauro Carvalho Chehab
Quoted 22 lines
Before this patch, building htmldocs on opensuseLEAP works fine:
# make htmldocs Available Python versions: /usr/bin/python3.11Python 3.6.15 not supported. Changing to
/usr/bin/python3.11Python 3.6.15 not supported. Changing to/usr/bin/python3.11Using 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:
Quoted 7 lines
Quoted 4 lines
$ 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