From nobody Thu Oct 2 13:03:47 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 8C53931A7FE; Wed, 17 Sep 2025 12:15:55 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1758111355; cv=none; b=J/YwXAI+cEHWAJnwpODfpWQ6Zrou15+nYLU95aV6SyRCUoxzEL6yu6Dt94burMxxCQ9g5gYpCHF6/UcG2rwFP/EP90riYzYU8X27I0G5gUHp5+kr1SO+o8RyoZvfEiuBTsYYAAKs0pKeD7OYnTdgF9+eJX0YqF9YN9Xzs0FrHm4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1758111355; c=relaxed/simple; bh=xi6aaKetpX4fDfqLRLgmvyJ++GISVlfrcSwACNlUxeU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=hBsnac4hQY2lmnJxHclK9THSiFp03BuDffgCjInscxBnZEBsw5ltSc+Y4h1+M1L9OonxFin34rEs+a4nk1crBHqTTTRBtkHPqfi5sC2Dbf/Fv9ekTKRASg2Xw6sba7vC/UeOc3nbHh+VQw4kxYchRVH8IK9vCezXwLFqirJtblU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ubxjd3Rt; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="ubxjd3Rt" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 33346C4CEFB; Wed, 17 Sep 2025 12:15:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1758111355; bh=xi6aaKetpX4fDfqLRLgmvyJ++GISVlfrcSwACNlUxeU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ubxjd3RtVhTUrp69IIre1zcMwuzT3PV8wJf44Cm7SdfKbHBdqMhd5O+ilgXBPRDAY G0gEKSaHI+v2UoCxcYkFaX9OKzm6JsE9bpvkPO87A06oR9mcuvkz859Mnuwysbu7nf T2NrM5w9XTl+hyLRcM43Km/5vhXmEQVah1WJhKyOXTjLJnB8cCQpAUTRjUXnQyG14U gNHUranFt2MwvbJgNEsysZhqLNM2ZgZRnQKN0pnTZ2XwZ4tfd6PwbKowq3wFMVkMGm 8Wsz7JVbv5k5y64p5bQOUOszo7M04Dqg5rQ6JMFLokIpCQplZrcyOsUwO/5Ux7gM4B VA3yiLLdfWl2w== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uyr4h-0000000CGee-2ma4; Wed, 17 Sep 2025 14:15:51 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , =?UTF-8?q?Bj=C3=B6rn=20Roy=20Baron?= , "Mauro Carvalho Chehab" , Alex Gaynor , Alice Ryhl , Andreas Hindborg , Benno Lossin , Boqun Feng , Danilo Krummrich , Gary Guo , Miguel Ojeda , Trevor Gross , linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org Subject: [PATCH v7 23/24] tools/docs: sphinx-* break documentation bulds on openSUSE Date: Wed, 17 Sep 2025 14:15:17 +0200 Message-ID: <43c10221cc1a6ccd0b7b84fc8ffc92ff02d7d0fb.1758111077.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.51.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" 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 tools/docs/sphinx-build-wrapper htmldocs \ --sphinxdirs=3D. --conf=3Dconf.py --builddir=3DDocumentation/output= --theme=3D --css=3D \ --paper=3D Python 3.6.15 not supported. Bailing out make[2]: *** [Documentation/Makefile:76: htmldocs] Error 1 make[1]: *** [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 tools/docs/sphinx-build-wrapper htmldocs --sphinxdir= s=3D. --conf=3Dconf.py --theme=3D --css=3D --paper=3D 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 --- tools/docs/lib/python_version.py | 28 ++++++++++++++++++++++++---- tools/docs/sphinx-build-wrapper | 3 ++- tools/docs/sphinx-pre-install | 3 ++- 3 files changed, 28 insertions(+), 6 deletions(-) diff --git a/tools/docs/lib/python_version.py b/tools/docs/lib/python_versi= on.py index a9fda2470a26..4fde1b882164 100644 --- a/tools/docs/lib/python_version.py +++ b/tools/docs/lib/python_version.py @@ -20,9 +20,11 @@ Python version if present. import os import re import subprocess +import shlex import sys =20 from glob import glob +from textwrap import indent =20 class PythonVersion: """ @@ -44,6 +46,25 @@ class PythonVersion: """Returns a version tuple as major.minor.patch""" return ".".join([str(x) for x in version]) =20 + @staticmethod + def cmd_print(cmd, max_len=3D80): + cmd_line =3D [] + + for w in cmd: + w =3D shlex.quote(w) + + if cmd_line: + if not max_len or len(cmd_line[-1]) + len(w) < max_len: + cmd_line[-1] +=3D " " + w + continue + else: + cmd_line[-1] +=3D " \\" + cmd_line.append(w) + else: + cmd_line.append(w) + + return "\n ".join(cmd_line) + def __str__(self): """Returns a version tuple as major.minor.patch from self.version"= "" return self.ver_str(self.version) @@ -130,14 +151,13 @@ class PythonVersion: else: new_python_cmd =3D None =20 - if show_alternatives: + if show_alternatives and available_versions: print("You could run, instead:") for _, cmd in available_versions: args =3D [cmd, script_path] + sys.argv[1:] =20 - cmd_str =3D " ".join(args) - print(f" {cmd_str}") - print() + cmd_str =3D indent(PythonVersion.cmd_print(args), " ") + print(f"{cmd_str}\n") =20 if bail_out: msg =3D f"Python {python_ver} not supported. Bailing out" diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index e24486dede76..103b0044bb0b 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -774,7 +774,8 @@ def main(): =20 args =3D parser.parse_args() =20 - PythonVersion.check_python(MIN_PYTHON_VERSION) + PythonVersion.check_python(MIN_PYTHON_VERSION, show_alternatives=3DTru= e, + bail_out=3DTrue) =20 builder =3D SphinxBuilder(builddir=3Dargs.builddir, verbose=3Dargs.verbose, n_jobs=3Dargs.jobs, 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(): =20 checker =3D SphinxDependencyChecker(args) =20 - PythonVersion.check_python(MIN_PYTHON_VERSION) + PythonVersion.check_python(MIN_PYTHON_VERSION, + bail_out=3DTrue, success_on_error=3DTrue) checker.check_needs() =20 # Call main if not used as module --=20 2.51.0