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

[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