From nobody Thu Oct 9 01:16:06 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 9BB9DA47; Sun, 22 Jun 2025 06:02:51 +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=1750572171; cv=none; b=Ma5uPjKxMn9ZuZAaG4GyBJhtuyp0W/I/cEEsEPtbHyr/yvJViyTqlnDMvEeVykq5cP2ztpwoWuSGwFhBi7qq9iw16JKJJN+9V2iFvVjTNvXaN5a9lmA32eSfvLqOihi4fgO9Ik7XGQkes8WV+9ormptE12IYmpaSqa5TnYzBi2w= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572171; c=relaxed/simple; bh=rpsVQaefgMO9qukOwI9h7kF6VHQFcBEbI70UXJr2STI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=kyySXhAasXXIa4iBBaPfCSK9WBqk7vP+ouknbW4lMKlqtUNWkV26MOLpfmt8OWM46C2YcDuCGG4yp90jlyTil6+Iew3nMQi511epbnyg154shzRbMCJPrQTcGrRONcpW3T2tqIoZs64F7d/164ywwRi6oWC7Z63InCJ9j2Y3Vq4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=XCxMh4DZ; 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="XCxMh4DZ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2B717C4CEF1; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=rpsVQaefgMO9qukOwI9h7kF6VHQFcBEbI70UXJr2STI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XCxMh4DZ5FNk4Q7Xt3MPzG4u2WEBJXK5OlyhjCgWgjtrDn+UM2G/1B5Ex4e5TMKtr j+6CphrNV/BzVu3I4/EMkgcK3zb2KAlCVQkzovCS4JmigQtaZw9XFArKVZICihzisz kGzVDNNLEeGkW4QDS/+1Uhegd47c4kKEGT6f18oMZyRDrJWkG+ZLzfvMFiodRLk2bO 3llvgerUjmCuPVCkKNQqt78gK1TEMaceWG11BCEy3r/I82Xd9k7tOukvbQEQ4ay6mZ xSGeUe3Z+SCuoAZ+6NurWNARBUdX7TRLpgzIswbpdrHwzaoFLY5Ks4gqGaehXUchbg f5RgkoHfLw/iA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o24-1EwN; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org, Donald Hunter Subject: [PATCH v3 01/15] docs: conf.py: properly handle include and exclude patterns Date: Sun, 22 Jun 2025 08:02:30 +0200 Message-ID: <429c9c670fe27860f5e4f29aaf72576a4ed52ad1.1750571906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" When one does: make SPHINXDIRS=3D"foo" htmldocs All patterns would be relative to Documentation/foo, which causes the include/exclude patterns like: include_patterns =3D [ ... f'foo/*.{ext}', ] to break. This is not what it is expected. Address it by adding a logic to dynamically adjust the pattern when SPHINXDIRS is used. That allows adding parsers for other file types. It should be noticed that include_patterns was added on Sphinx 5.1: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-incl= ude_patterns So, a backward-compatible code is needed when we start using it for real. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Donald Hunter --- Documentation/conf.py | 67 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 63 insertions(+), 4 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 12de52a2b17e..91ce2b1c33cc 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -17,6 +17,66 @@ import os import sphinx import shutil =20 +# Get Sphinx version +major, minor, patch =3D sphinx.version_info[:3] + +# Include_patterns were added on Sphinx 5.1 +if (major < 5) or (major =3D=3D 5 and minor < 1): + has_include_patterns =3D False +else: + has_include_patterns =3D True + # Include patterns that don't contain directory names, in glob format + include_patterns =3D ['**.rst'] + +# Location of Documentation/ directory +doctree =3D os.path.abspath('.') + +# Exclude of patterns that don't contain directory names, in glob format. +exclude_patterns =3D [] + +# List of patterns that contain directory names in glob format. +dyn_include_patterns =3D [] +dyn_exclude_patterns =3D ['output'] + +# Properly handle include/exclude patterns +# ---------------------------------------- + +def update_patterns(app, config): + + """ + On Sphinx, all directories are relative to what it is passed as + SOURCEDIR parameter for sphinx-build. Due to that, all patterns + that have directory names on it need to be dynamically set, after + converting them to a relative patch. + + As Sphinx doesn't include any patterns outside SOURCEDIR, we should + exclude relative patterns that start with "../". + """ + + sourcedir =3D app.srcdir # full path to the source directory + builddir =3D os.environ.get("BUILDDIR") + + # setup include_patterns dynamically + if has_include_patterns: + for p in dyn_include_patterns: + full =3D os.path.join(doctree, p) + + rel_path =3D os.path.relpath(full, start =3D app.srcdir) + if rel_path.startswith("../"): + continue + + config.include_patterns.append(rel_path) + + # setup exclude_patterns dynamically + for p in dyn_exclude_patterns: + full =3D os.path.join(doctree, p) + + rel_path =3D os.path.relpath(full, start =3D app.srcdir) + if rel_path.startswith("../"): + continue + + config.exclude_patterns.append(rel_path) + # helper # ------ =20 @@ -219,10 +279,6 @@ language =3D 'en' # Else, today_fmt is used as the format for a strftime call. #today_fmt =3D '%B %d, %Y' =20 -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns =3D ['output'] - # The reST default role (used for this markup: `text`) to use for all # documents. #default_role =3D None @@ -516,3 +572,6 @@ kerneldoc_srctree =3D '..' # the last statement in the conf.py file # ------------------------------------------------------------------------= ------ loadConfig(globals()) + +def setup(app): + app.connect('config-inited', update_patterns) --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 9BBD9481C4; Sun, 22 Jun 2025 06:02:51 +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=1750572171; cv=none; b=lYvtcgXC6v8WOv5X2gNxnQwcWReH5juF1vUffRSO9yN5ZzI9NQrqJIpj/YhxhIfEGXXJT+AtYQzhu6cZqcc9vk/I5xXrMEv/nwP6z/MnYw9Cbz9B+20qf7g7+UNxmEFPwFR1127/dgrJXU2pgP+j8kglznsuz8okPqU8g9SBMhE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572171; c=relaxed/simple; bh=9sv3o8O8M0IyOR5wJkoSEusaPecRlQcEL5SoMo0iJ7A=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=VvoEAZ0eSQNLEbdLj8BRlGRysfyOr+Xga4JwAjR1ViGlBXD3/ng5TMrY0oi2TlobGPOdRcn2Dsusrvupp4jyRJ+wwG5kW2/COfBlPsfyJcT0mWrmizEVyEN+XW1FgzIoqn5gWtCDaGI9Dz23GPhxzm5TpdjVTdcWHuQbli9PKOA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=PWYycLpX; 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="PWYycLpX" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 342C6C4CEF4; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=9sv3o8O8M0IyOR5wJkoSEusaPecRlQcEL5SoMo0iJ7A=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PWYycLpXYVVCTDduwZsyo6x2f0ct9XJvpZPJuxOXnz5mHcdFh2qg7Mtx8ciW2BL8Y A+zQomcwmCJ/PFwyq1sKxvIacIC+HOYuPCySm8s9qwtvyZ7UG0aHt2XcItUv8XK8DE XOzdHBsukwyEpulHUWobmn85v4mj74CUDvqtKJUHoknAvzX/CybAh/gpHIGqzA5Et5 blkjoW0L84a8AZXVh27FY/H25wqaAL+qiYFprcWT5opgNGDAtuawvXS0Ghi/zFgIN2 zmXQ2p2SgRb5cHykuYIyywTGMlzmKihGzWDCb5GYnueWfU9ZkHzDt9nqTPf4DnJ8bd 0FDKZyFH216kw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o28-1LnW; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org, Breno Leitao , Donald Hunter Subject: [PATCH v3 02/15] docs: Makefile: disable check rules on make cleandocs Date: Sun, 22 Jun 2025 08:02:31 +0200 Message-ID: <8386afcee494c9e81d051c83235150104e3a2949.1750571906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" It doesn't make sense to check for missing ABI and documents when cleaning the tree. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Breno Leitao Reviewed-by: Donald Hunter --- Documentation/Makefile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/Makefile b/Documentation/Makefile index d30d66ddf1ad..b98477df5ddf 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -5,6 +5,7 @@ # for cleaning subdir- :=3D devicetree/bindings =20 +ifneq ($(MAKECMDGOALS),cleandocs) # Check for broken documentation file references ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y) $(shell $(srctree)/scripts/documentation-file-ref-check --warn) @@ -14,6 +15,7 @@ endif ifeq ($(CONFIG_WARN_ABI_ERRORS),y) $(shell $(srctree)/scripts/get_abi.py --dir $(srctree)/Documentation/ABI v= alidate) endif +endif =20 # You can set these variables from the command line. SPHINXBUILD =3D sphinx-build --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 E4D1818C91F; Sun, 22 Jun 2025 06:02:51 +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=1750572172; cv=none; b=C3vusFsnZLgC30qpwolwObsmQv15ZgQzZ0fh8nDIY2j+CYue6UoAu527J3MySseTbbmnLbO+961VURULwtTwgtOVc42kjs3FWBmyToMT9g3JqFeWwbluc5qcC1kdwMgzPJ7KvmG0ikzJVHHDwYJkR+fYPx8bOYrSN3OqvlD0998= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572172; c=relaxed/simple; bh=wx0BDvaHpPo9dP1wTRMAhz/5i+/h4gNQceHfFlSoK7g=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=MQYg9xFIX9jY3EPYmzjLjchhHzgW83cfrkAjtbABDDz7PGekDp/q0d/8VJeIkOVW4DGiuJwaNKa7unIcgLQTumiVEN1vmyMQVgnZv3yoqZJ94snYIlP1iGqm5Jjodm5gmj8UMPD4xH9OoryjAFIJGpzZ3DWIeOiTzytkxCzT+OY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=NBM068TF; 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="NBM068TF" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 29522C4CEE3; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=wx0BDvaHpPo9dP1wTRMAhz/5i+/h4gNQceHfFlSoK7g=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=NBM068TF+zbmMp0P/AAnSJGbxDKfwvx3g3pFbNprXtaPhA5qHcO/RQ4Ky2iTUD4E2 gQWeQO0FQNazvhxDOz5YC/97htyHDdRFv/2qG5Bw79xn49ztx/oDzOeifQTdWshMc2 6Hecvmia1JqnQyM5BcRgWi4dQzz8CA2+gsQVlx+XODff3cspKpN+7dblKBYYVC30Lf +cUKMKXIQ68RmCOuka3jUnTYPy/h/g7RMlu8g0rRAhFXokXTo3Yc5KrqyDBK+eILHZ nTFUb87Of2Xum+HpEbBMd/yqAh/cU9ndgepe7gkvEiWS3yMPZPAmg7641yHI5P3+Cc FsJ8BMl2kKJpA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o2C-1Slt; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v3 03/15] scripts: scripts/test_doc_build.py: add script to test doc build Date: Sun, 22 Jun 2025 08:02:32 +0200 Message-ID: <93faf6c35ec865566246ca094868a8e6d85dde39.1750571906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" Testing Sphinx backward-compatibility is hard, as per version minimal Python dependency requirements can be a nightmare. Add a script to help automate such checks. Signed-off-by: Mauro Carvalho Chehab --- scripts/test_doc_build.py | 241 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100755 scripts/test_doc_build.py diff --git a/scripts/test_doc_build.py b/scripts/test_doc_build.py new file mode 100755 index 000000000000..482716fbe91d --- /dev/null +++ b/scripts/test_doc_build.py @@ -0,0 +1,241 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright(c) 2025: Mauro Carvalho Chehab +# +# pylint: disable=3DC0103,R1715 + +""" +Install minimal supported requirements for different Sphinx versions +and optionally test the build. +""" + +import argparse +import os.path +import sys +import time + +from subprocess import run + +# Minimal python version supported by the building system +python_bin =3D "python3.9" + +# Starting from 8.0.2, Python 3.9 becomes too old +python_changes =3D {(8, 0, 2): "python3"} + +# Sphinx versions to be installed and their incremental requirements +sphinx_requirements =3D { + (3, 4, 3): { + "alabaster": "0.7.13", + "babel": "2.17.0", + "certifi": "2025.6.15", + "charset-normalizer": "3.4.2", + "docutils": "0.15", + "idna": "3.10", + "imagesize": "1.4.1", + "Jinja2": "3.0.3", + "MarkupSafe": "2.0", + "packaging": "25.0", + "Pygments": "2.19.1", + "PyYAML": "5.1", + "requests": "2.32.4", + "snowballstemmer": "3.0.1", + "sphinxcontrib-applehelp": "1.0.4", + "sphinxcontrib-devhelp": "1.0.2", + "sphinxcontrib-htmlhelp": "2.0.1", + "sphinxcontrib-jsmath": "1.0.1", + "sphinxcontrib-qthelp": "1.0.3", + "sphinxcontrib-serializinghtml": "1.1.5", + "urllib3": "2.4.0", + }, + (3, 5, 4): {}, + (4, 0, 3): { + "docutils": "0.17.1", + "PyYAML": "5.1", + }, + (4, 1, 2): {}, + (4, 3, 2): {}, + (4, 4, 0): {}, + (4, 5, 0): {}, + (5, 0, 2): {}, + (5, 1, 1): {}, + (5, 2, 3): { + "Jinja2": "3.1.2", + "MarkupSafe": "2.0", + "PyYAML": "5.3.1", + }, + (5, 3, 0): { + "docutils": "0.18.1", + "PyYAML": "5.3.1", + }, + (6, 0, 1): {}, + (6, 1, 3): {}, + (6, 2, 1): { + "PyYAML": "5.4.1", + }, + (7, 0, 1): {}, + (7, 1, 2): {}, + (7, 2, 3): { + "PyYAML": "6.0.1", + "sphinxcontrib-serializinghtml": "1.1.9", + }, + (7, 3, 7): { + "alabaster": "0.7.14", + "PyYAML": "6.0.1", + }, + (7, 4, 7): { + "docutils": "0.20", + "PyYAML": "6.0.1", + }, + (8, 0, 2): {}, + (8, 1, 3): { + "PyYAML": "6.0.1", + "sphinxcontrib-applehelp": "1.0.7", + "sphinxcontrib-devhelp": "1.0.6", + "sphinxcontrib-htmlhelp": "2.0.6", + "sphinxcontrib-qthelp": "1.0.6", + }, + (8, 2, 3): { + "PyYAML": "6.0.1", + "sphinxcontrib-serializinghtml": "1.1.9", + }, +} + + +def parse_version(ver_str): + """Convert a version string into a tuple.""" + + return tuple(map(int, ver_str.split("."))) + + +parser =3D argparse.ArgumentParser(description=3D"Build docs for different= sphinx_versions.") + +parser.add_argument('-v', '--version', help=3D'Sphinx single version', + type=3Dparse_version) +parser.add_argument('--min-version', "--min", help=3D'Sphinx minimal versi= on', + type=3Dparse_version) +parser.add_argument('--max-version', "--max", help=3D'Sphinx maximum versi= on', + type=3Dparse_version) +parser.add_argument('-a', '--make_args', + help=3D'extra arguments for make htmldocs, like SPHINX= DIRS=3Dnetlink/specs', + nargs=3D"*") +parser.add_argument('-w', '--write', help=3D'write a requirements.txt file= ', + action=3D'store_true') +parser.add_argument('-m', '--make', + help=3D'Make documentation', + action=3D'store_true') +parser.add_argument('-i', '--wait-input', + help=3D'Wait for an enter before going to the next ver= sion', + action=3D'store_true') + +args =3D parser.parse_args() + +if not args.make_args: + args.make_args =3D [] + +if args.version: + if args.min_version or args.max_version: + sys.exit("Use either --version or --min-version/--max-version") + else: + args.min_version =3D args.version + args.max_version =3D args.version + +sphinx_versions =3D sorted(list(sphinx_requirements.keys())) + +if not args.min_version: + args.min_version =3D sphinx_versions[0] + +if not args.max_version: + args.max_version =3D sphinx_versions[-1] + +first_run =3D True +cur_requirements =3D {} +built_time =3D {} + +for cur_ver, new_reqs in sphinx_requirements.items(): + cur_requirements.update(new_reqs) + + if cur_ver in python_changes: + python_bin =3D python_changes[cur_ver] + + ver =3D ".".join(map(str, cur_ver)) + + if args.min_version: + if cur_ver < args.min_version: + continue + + if args.max_version: + if cur_ver > args.max_version: + break + + if not first_run and args.wait_input and args.make: + ret =3D input("Press Enter to continue or 'a' to abort: ").strip()= .lower() + if ret =3D=3D "a": + print("Aborted.") + sys.exit() + else: + first_run =3D False + + venv_dir =3D f"Sphinx_{ver}" + req_file =3D f"requirements_{ver}.txt" + + print(f"\nSphinx {ver} with {python_bin}") + + # Create venv + run([python_bin, "-m", "venv", venv_dir], check=3DTrue) + pip =3D os.path.join(venv_dir, "bin/pip") + + # Create install list + reqs =3D [] + for pkg, verstr in cur_requirements.items(): + reqs.append(f"{pkg}=3D=3D{verstr}") + + reqs.append(f"Sphinx=3D=3D{ver}") + + run([pip, "install"] + reqs, check=3DTrue) + + # Freeze environment + result =3D run([pip, "freeze"], capture_output=3DTrue, text=3DTrue, ch= eck=3DTrue) + + # Pip install succeeded. Write requirements file + if args.write: + with open(req_file, "w", encoding=3D"utf-8") as fp: + fp.write(result.stdout) + + if args.make: + start_time =3D time.time() + + # Prepare a venv environment + env =3D os.environ.copy() + bin_dir =3D os.path.join(venv_dir, "bin") + env["PATH"] =3D bin_dir + ":" + env["PATH"] + env["VIRTUAL_ENV"] =3D venv_dir + if "PYTHONHOME" in env: + del env["PYTHONHOME"] + + # Test doc build + run(["make", "cleandocs"], env=3Denv, check=3DTrue) + make =3D ["make"] + args.make_args + ["htmldocs"] + + print(f". {bin_dir}/activate") + print(" ".join(make)) + print("deactivate") + run(make, env=3Denv, check=3DTrue) + + end_time =3D time.time() + elapsed_time =3D end_time - start_time + hours, minutes =3D divmod(elapsed_time, 3600) + minutes, seconds =3D divmod(minutes, 60) + + hours =3D int(hours) + minutes =3D int(minutes) + seconds =3D int(seconds) + + built_time[ver] =3D f"{hours:02d}:{minutes:02d}:{seconds:02d}" + + print(f"Finished doc build for Sphinx {ver}. Elapsed time: {built_= time[ver]}") + +if args.make: + print() + print("Summary:") + for ver, elapsed_time in sorted(built_time.items()): + print(f"\tSphinx {ver} elapsed time: {elapsed_time}") --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 2080E192590; Sun, 22 Jun 2025 06:02:51 +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=1750572172; cv=none; b=pAlvis6GajdglvagZKRmxPXGQ0Ocu+UlfXXkFVVDPkrvRQXPAWmkRx2b7iwDtLEfBhbWKh9OtmQu+s/G+y4MX//M0ku2byxAKaDb1zPl/41BkauZ3jtPKWLjr/bhpRNUmx9D04aGHczae2C3ODmYIP716a/ZlXz1SuG2lpJ2Kjg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572172; c=relaxed/simple; bh=XT+7KR3Tg4iAhlUU3c6mKrOGy1MIPvbKyEPBCyZpAmw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=tBEO7o75fPS1nIlaIRU9IdLHXvSjK8qDa68GCHRBy00TTNSirR53hhIK+MQA3I4Bpg5BDRAqsjzGA6rJJRRlwXh3ElF6dBHYLdlP7xckFfLLf11E5YRXoKlis/Eu0iH1ccNhS+yDXLXIX67Nq2r8g7XmMRUXEGw5WI7HB5CG2aM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=rEFcxNQE; 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="rEFcxNQE" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 317A3C4CEF2; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=XT+7KR3Tg4iAhlUU3c6mKrOGy1MIPvbKyEPBCyZpAmw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=rEFcxNQEoRDQPdcN+3RTZPO2y1AS7EBTVHtql9cqKTurvXAQODelenF4AygqSHKwN 2NOiIGTy9wgVbIBmDdlIyQVyiWEJur7wAK5R8aq4eTdA+9m5C96wzwnja2kZFqLyeW ++jnZ+Ja5SdxYvWj9nCTQd/Q/J/6XK6fD4dO1s20Os5HpAa/wUA7w+3NeX+vIiX4uJ 1LcTnvULm+xnxuSVQ2hN1S81q/Gzcs1jf+IhF02ly8fAH8lDbYz40tpkfVm0ICTh5p 3oAk0pLaakeTPMbQd4bh8cJqwd0Wf0rgeWRId9yX4kQxzNOj3V69XI1RKGlpctqlB2 e3szlHPdM4uQw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o2G-1a2O; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v3 04/15] scripts: test_doc_build.py: make capture assynchronous Date: Sun, 22 Jun 2025 08:02:33 +0200 Message-ID: <9b0a60b5047137b5ba764701268da992767b128c.1750571906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" Prepare the tool to allow writing the output into log files. For such purpose, receive stdin/stdout messages asynchronously. Signed-off-by: Mauro Carvalho Chehab --- scripts/test_doc_build.py | 393 +++++++++++++++++++++++++------------- 1 file changed, 255 insertions(+), 138 deletions(-) diff --git a/scripts/test_doc_build.py b/scripts/test_doc_build.py index 482716fbe91d..94f2f2d8c3b7 100755 --- a/scripts/test_doc_build.py +++ b/scripts/test_doc_build.py @@ -2,7 +2,7 @@ # SPDX-License-Identifier: GPL-2.0 # Copyright(c) 2025: Mauro Carvalho Chehab # -# pylint: disable=3DC0103,R1715 +# pylint: disable=3DR0903,R0913,R0914,R0917 =20 """ Install minimal supported requirements for different Sphinx versions @@ -10,20 +10,20 @@ and optionally test the build. """ =20 import argparse +import asyncio import os.path import sys import time - -from subprocess import run +import subprocess =20 # Minimal python version supported by the building system -python_bin =3D "python3.9" +MINIMAL_PYTHON_VERSION =3D "python3.9" =20 # Starting from 8.0.2, Python 3.9 becomes too old -python_changes =3D {(8, 0, 2): "python3"} +PYTHON_VER_CHANGES =3D {(8, 0, 2): "python3"} =20 # Sphinx versions to be installed and their incremental requirements -sphinx_requirements =3D { +SPHINX_REQUIREMENTS =3D { (3, 4, 3): { "alabaster": "0.7.13", "babel": "2.17.0", @@ -101,141 +101,258 @@ sphinx_requirements =3D { } =20 =20 +class AsyncCommands: + """Excecute command synchronously""" + + stdout =3D None + stderr =3D None + output =3D None + + async def _read(self, stream, verbose, is_info): + """Ancillary routine to capture while displaying""" + + while stream is not None: + line =3D await stream.readline() + if line: + out =3D line.decode("utf-8", errors=3D"backslashreplace") + self.output +=3D out + if is_info: + if verbose: + print(out.rstrip("\n")) + + self.stdout +=3D out + else: + if verbose: + print(out.rstrip("\n"), file=3Dsys.stderr) + + self.stderr +=3D out + else: + break + + async def run(self, cmd, capture_output=3DFalse, check=3DFalse, + env=3DNone, verbose=3DTrue): + + """ + Execute an arbitrary command, handling errors. + + Please notice that this class is not thread safe + """ + + self.stdout =3D "" + self.stderr =3D "" + self.output =3D "" + + if verbose: + print("$ ", " ".join(cmd)) + + proc =3D await asyncio.create_subprocess_exec(cmd[0], + *cmd[1:], + env=3Denv, + stdout=3Dasyncio.subpr= ocess.PIPE, + stderr=3Dasyncio.subpr= ocess.PIPE) + + # Handle input and output in realtime + await asyncio.gather( + self._read(proc.stdout, verbose, True), + self._read(proc.stderr, verbose, False), + ) + + await proc.wait() + + if check and proc.returncode > 0: + raise subprocess.CalledProcessError(returncode=3Dproc.returnco= de, + cmd=3D" ".join(cmd), + output=3Dself.stdout, + stderr=3Dself.stderr) + + if capture_output: + if proc.returncode > 0: + print("Error {proc.returncode}", file=3Dsys.stderr) + return "" + + return self.output + + ret =3D subprocess.CompletedProcess(args=3Dcmd, + returncode=3Dproc.returncode, + stdout=3Dself.stdout, + stderr=3Dself.stderr) + + return ret + + +class SphinxVenv: + """ + Installs Sphinx on one virtual env per Sphinx version with a minimal + set of dependencies, adjusting them to each specific version. + """ + + def __init__(self): + """Initialize instance variables""" + + self.built_time =3D {} + self.first_run =3D True + + async def _handle_version(self, args, cur_ver, cur_requirements, pytho= n_bin): + """Handle a single Sphinx version""" + + cmd =3D AsyncCommands() + + ver =3D ".".join(map(str, cur_ver)) + + if not self.first_run and args.wait_input and args.make: + ret =3D input("Press Enter to continue or 'a' to abort: ").str= ip().lower() + if ret =3D=3D "a": + print("Aborted.") + sys.exit() + else: + self.first_run =3D False + + venv_dir =3D f"Sphinx_{ver}" + req_file =3D f"requirements_{ver}.txt" + + print(f"\nSphinx {ver} with {python_bin}") + + # Create venv + await cmd.run([python_bin, "-m", "venv", venv_dir], check=3DTrue) + pip =3D os.path.join(venv_dir, "bin/pip") + + # Create install list + reqs =3D [] + for pkg, verstr in cur_requirements.items(): + reqs.append(f"{pkg}=3D=3D{verstr}") + + reqs.append(f"Sphinx=3D=3D{ver}") + + await cmd.run([pip, "install"] + reqs, check=3DTrue, verbose=3DTru= e) + + # Freeze environment + result =3D await cmd.run([pip, "freeze"], verbose=3DFalse, check= =3DTrue) + + # Pip install succeeded. Write requirements file + if args.write: + with open(req_file, "w", encoding=3D"utf-8") as fp: + fp.write(result.stdout) + + if args.make: + start_time =3D time.time() + + # Prepare a venv environment + env =3D os.environ.copy() + bin_dir =3D os.path.join(venv_dir, "bin") + env["PATH"] =3D bin_dir + ":" + env["PATH"] + env["VIRTUAL_ENV"] =3D venv_dir + if "PYTHONHOME" in env: + del env["PYTHONHOME"] + + # Test doc build + await cmd.run(["make", "cleandocs"], env=3Denv, check=3DTrue) + make =3D ["make"] + args.make_args + ["htmldocs"] + + print(f". {bin_dir}/activate") + print(" ".join(make)) + print("deactivate") + await cmd.run(make, env=3Denv, check=3DTrue) + + end_time =3D time.time() + elapsed_time =3D end_time - start_time + hours, minutes =3D divmod(elapsed_time, 3600) + minutes, seconds =3D divmod(minutes, 60) + + hours =3D int(hours) + minutes =3D int(minutes) + seconds =3D int(seconds) + + self.built_time[ver] =3D f"{hours:02d}:{minutes:02d}:{seconds:= 02d}" + + print(f"Finished doc build for Sphinx {ver}. Elapsed time: {se= lf.built_time[ver]}") + + async def run(self, args): + """ + Navigate though multiple Sphinx versions, handling each of them + on a loop. + """ + + cur_requirements =3D {} + python_bin =3D MINIMAL_PYTHON_VERSION + + for cur_ver, new_reqs in SPHINX_REQUIREMENTS.items(): + cur_requirements.update(new_reqs) + + if cur_ver in PYTHON_VER_CHANGES: # pylint: disable= =3DR1715 + + python_bin =3D PYTHON_VER_CHANGES[cur_ver] + + if args.min_version: + if cur_ver < args.min_version: + continue + + if args.max_version: + if cur_ver > args.max_version: + break + + await self._handle_version(args, cur_ver, cur_requirements, + python_bin) + + if args.make: + print() + print("Summary:") + for ver, elapsed_time in sorted(self.built_time.items()): + print(f"\tSphinx {ver} elapsed time: {elapsed_time}") + + def parse_version(ver_str): """Convert a version string into a tuple.""" =20 return tuple(map(int, ver_str.split("."))) =20 =20 -parser =3D argparse.ArgumentParser(description=3D"Build docs for different= sphinx_versions.") - -parser.add_argument('-v', '--version', help=3D'Sphinx single version', - type=3Dparse_version) -parser.add_argument('--min-version', "--min", help=3D'Sphinx minimal versi= on', - type=3Dparse_version) -parser.add_argument('--max-version', "--max", help=3D'Sphinx maximum versi= on', - type=3Dparse_version) -parser.add_argument('-a', '--make_args', - help=3D'extra arguments for make htmldocs, like SPHINX= DIRS=3Dnetlink/specs', - nargs=3D"*") -parser.add_argument('-w', '--write', help=3D'write a requirements.txt file= ', - action=3D'store_true') -parser.add_argument('-m', '--make', - help=3D'Make documentation', - action=3D'store_true') -parser.add_argument('-i', '--wait-input', - help=3D'Wait for an enter before going to the next ver= sion', - action=3D'store_true') - -args =3D parser.parse_args() - -if not args.make_args: - args.make_args =3D [] - -if args.version: - if args.min_version or args.max_version: - sys.exit("Use either --version or --min-version/--max-version") - else: - args.min_version =3D args.version - args.max_version =3D args.version - -sphinx_versions =3D sorted(list(sphinx_requirements.keys())) - -if not args.min_version: - args.min_version =3D sphinx_versions[0] - -if not args.max_version: - args.max_version =3D sphinx_versions[-1] - -first_run =3D True -cur_requirements =3D {} -built_time =3D {} - -for cur_ver, new_reqs in sphinx_requirements.items(): - cur_requirements.update(new_reqs) - - if cur_ver in python_changes: - python_bin =3D python_changes[cur_ver] - - ver =3D ".".join(map(str, cur_ver)) - - if args.min_version: - if cur_ver < args.min_version: - continue - - if args.max_version: - if cur_ver > args.max_version: - break - - if not first_run and args.wait_input and args.make: - ret =3D input("Press Enter to continue or 'a' to abort: ").strip()= .lower() - if ret =3D=3D "a": - print("Aborted.") - sys.exit() - else: - first_run =3D False - - venv_dir =3D f"Sphinx_{ver}" - req_file =3D f"requirements_{ver}.txt" - - print(f"\nSphinx {ver} with {python_bin}") - - # Create venv - run([python_bin, "-m", "venv", venv_dir], check=3DTrue) - pip =3D os.path.join(venv_dir, "bin/pip") - - # Create install list - reqs =3D [] - for pkg, verstr in cur_requirements.items(): - reqs.append(f"{pkg}=3D=3D{verstr}") - - reqs.append(f"Sphinx=3D=3D{ver}") - - run([pip, "install"] + reqs, check=3DTrue) - - # Freeze environment - result =3D run([pip, "freeze"], capture_output=3DTrue, text=3DTrue, ch= eck=3DTrue) - - # Pip install succeeded. Write requirements file - if args.write: - with open(req_file, "w", encoding=3D"utf-8") as fp: - fp.write(result.stdout) - - if args.make: - start_time =3D time.time() - - # Prepare a venv environment - env =3D os.environ.copy() - bin_dir =3D os.path.join(venv_dir, "bin") - env["PATH"] =3D bin_dir + ":" + env["PATH"] - env["VIRTUAL_ENV"] =3D venv_dir - if "PYTHONHOME" in env: - del env["PYTHONHOME"] - - # Test doc build - run(["make", "cleandocs"], env=3Denv, check=3DTrue) - make =3D ["make"] + args.make_args + ["htmldocs"] - - print(f". {bin_dir}/activate") - print(" ".join(make)) - print("deactivate") - run(make, env=3Denv, check=3DTrue) - - end_time =3D time.time() - elapsed_time =3D end_time - start_time - hours, minutes =3D divmod(elapsed_time, 3600) - minutes, seconds =3D divmod(minutes, 60) - - hours =3D int(hours) - minutes =3D int(minutes) - seconds =3D int(seconds) - - built_time[ver] =3D f"{hours:02d}:{minutes:02d}:{seconds:02d}" - - print(f"Finished doc build for Sphinx {ver}. Elapsed time: {built_= time[ver]}") - -if args.make: - print() - print("Summary:") - for ver, elapsed_time in sorted(built_time.items()): - print(f"\tSphinx {ver} elapsed time: {elapsed_time}") +async def main(): + """Main program""" + + parser =3D argparse.ArgumentParser(description=3D"Build docs for diffe= rent sphinx_versions.") + + parser.add_argument('-v', '--version', help=3D'Sphinx single version', + type=3Dparse_version) + parser.add_argument('--min-version', "--min", help=3D'Sphinx minimal v= ersion', + type=3Dparse_version) + parser.add_argument('--max-version', "--max", help=3D'Sphinx maximum v= ersion', + type=3Dparse_version) + parser.add_argument('-a', '--make_args', + help=3D'extra arguments for make htmldocs, like SP= HINXDIRS=3Dnetlink/specs', + nargs=3D"*") + parser.add_argument('-w', '--write', help=3D'write a requirements.txt = file', + action=3D'store_true') + parser.add_argument('-m', '--make', + help=3D'Make documentation', + action=3D'store_true') + parser.add_argument('-i', '--wait-input', + help=3D'Wait for an enter before going to the next= version', + action=3D'store_true') + + args =3D parser.parse_args() + + if not args.make_args: + args.make_args =3D [] + + if args.version: + if args.min_version or args.max_version: + sys.exit("Use either --version or --min-version/--max-version") + else: + args.min_version =3D args.version + args.max_version =3D args.version + + sphinx_versions =3D sorted(list(SPHINX_REQUIREMENTS.keys())) + + if not args.min_version: + args.min_version =3D sphinx_versions[0] + + if not args.max_version: + args.max_version =3D sphinx_versions[-1] + + venv =3D SphinxVenv() + await venv.run(args) + + +# Call main method +if __name__ =3D=3D "__main__": + asyncio.run(main()) --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 E648018DB26; Sun, 22 Jun 2025 06:02:51 +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=1750572172; cv=none; b=M/67gYjzVFcf9Y1gtK0jJAjHip/fyYKRwX75+YQ0dqjfciss53O9IfbJ/ewfp70PgWeQcwq7fTjtancY1mw5P1YBsFErR1vfmTDWKZCjS78OSM6PIRircTpC/kpizN03LrF71EB0d7pC1JBkt7qL9Hwn30B0ytc7meAMvji9K2A= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572172; c=relaxed/simple; bh=t6WKKzUZ3jaz/IWeMR8qJbIf2p6B9ADIoUTLRFgr0u0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=bCcXZqvwLOQJ/lmw9/kuzXLO0ewfYreDvUN11JEY/8SODiEfmM3lJYY7GBnTQz0HL9WvPBF5/zELO0YommEtSOEfP3w25/LXGRYLMrjzdHE7ymWgJ9UeAdwCV7IN5zm03vnPmkXgJA4AakPQpyRQ88JYUq0zOuJ9ruB53KvNBbs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Zv+tUMK4; 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="Zv+tUMK4" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2DF52C4CEEA; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=t6WKKzUZ3jaz/IWeMR8qJbIf2p6B9ADIoUTLRFgr0u0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Zv+tUMK4MaP82Jddp8MV7KWBwi2R8LFoL7Byadjyty8Ns5Q1qVoVGrq2CLXwynLrx 0vD/jiGYisidp1O8IFo8oUQOgzaBP0DrVFwoSrNde27cxcN3MOJb9hG6gZFV1FrQsX Q9r7QuzX7kzy11mEzEFqyVb7AciU6j+RFkf8pvlTFLIzLuVEC9VCjyPndNYuiRi9tg J3b8KvfPFzQIevY8cukdHhv0Cu3pACF2NIjL7DDB7Iz+JRV5kPFsdIDc7+O4WkR93+ FEnRDG27G2PPv5wpVrDVDvRV+DPQXzyrmOfhmv/aG7C9Z26Yh7pLmPPMZZLOGqfLeo mqZrmRriudGKg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o2K-1h1B; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v3 05/15] scripts: test_doc_build.py: better control its output Date: Sun, 22 Jun 2025 08:02:34 +0200 Message-ID: <76c3a64a87a7493ae607d5c7784b3b829affcaf0.1750571906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" Now that asyncio is supported, allow userspace to adjust verbosity level and direct the script output to a file. Signed-off-by: Mauro Carvalho Chehab --- scripts/test_doc_build.py | 78 +++++++++++++++++++++++++-------------- 1 file changed, 51 insertions(+), 27 deletions(-) diff --git a/scripts/test_doc_build.py b/scripts/test_doc_build.py index 94f2f2d8c3b7..5b9eb2c0bf01 100755 --- a/scripts/test_doc_build.py +++ b/scripts/test_doc_build.py @@ -2,7 +2,7 @@ # SPDX-License-Identifier: GPL-2.0 # Copyright(c) 2025: Mauro Carvalho Chehab # -# pylint: disable=3DR0903,R0913,R0914,R0917 +# pylint: disable=3DR0903,R0912,R0913,R0914,R0917,C0301 =20 """ Install minimal supported requirements for different Sphinx versions @@ -104,9 +104,22 @@ SPHINX_REQUIREMENTS =3D { class AsyncCommands: """Excecute command synchronously""" =20 - stdout =3D None - stderr =3D None - output =3D None + def __init__(self, fp=3DNone): + + self.stdout =3D None + self.stderr =3D None + self.output =3D None + self.fp =3D fp + + def log(self, out, verbose, is_info=3DTrue): + if verbose: + if is_info: + print(out.rstrip("\n")) + else: + print(out.rstrip("\n"), file=3Dsys.stderr) + + if self.fp: + self.fp.write(out.rstrip("\n") + "\n") =20 async def _read(self, stream, verbose, is_info): """Ancillary routine to capture while displaying""" @@ -115,16 +128,10 @@ class AsyncCommands: line =3D await stream.readline() if line: out =3D line.decode("utf-8", errors=3D"backslashreplace") - self.output +=3D out + self.log(out, verbose, is_info) if is_info: - if verbose: - print(out.rstrip("\n")) - self.stdout +=3D out else: - if verbose: - print(out.rstrip("\n"), file=3Dsys.stderr) - self.stderr +=3D out else: break @@ -140,10 +147,8 @@ class AsyncCommands: =20 self.stdout =3D "" self.stderr =3D "" - self.output =3D "" =20 - if verbose: - print("$ ", " ".join(cmd)) + self.log("$ " + " ".join(cmd), verbose) =20 proc =3D await asyncio.create_subprocess_exec(cmd[0], *cmd[1:], @@ -167,7 +172,7 @@ class AsyncCommands: =20 if capture_output: if proc.returncode > 0: - print("Error {proc.returncode}", file=3Dsys.stderr) + self.log(f"Error {proc.returncode}", verbose=3DTrue, is_in= fo=3DFalse) return "" =20 return self.output @@ -192,10 +197,11 @@ class SphinxVenv: self.built_time =3D {} self.first_run =3D True =20 - async def _handle_version(self, args, cur_ver, cur_requirements, pytho= n_bin): + async def _handle_version(self, args, fp, + cur_ver, cur_requirements, python_bin): """Handle a single Sphinx version""" =20 - cmd =3D AsyncCommands() + cmd =3D AsyncCommands(fp) =20 ver =3D ".".join(map(str, cur_ver)) =20 @@ -210,10 +216,11 @@ class SphinxVenv: venv_dir =3D f"Sphinx_{ver}" req_file =3D f"requirements_{ver}.txt" =20 - print(f"\nSphinx {ver} with {python_bin}") + cmd.log(f"\nSphinx {ver} with {python_bin}", verbose=3DTrue) =20 # Create venv - await cmd.run([python_bin, "-m", "venv", venv_dir], check=3DTrue) + await cmd.run([python_bin, "-m", "venv", venv_dir], + verbose=3Dargs.verbose, check=3DTrue) pip =3D os.path.join(venv_dir, "bin/pip") =20 # Create install list @@ -223,7 +230,7 @@ class SphinxVenv: =20 reqs.append(f"Sphinx=3D=3D{ver}") =20 - await cmd.run([pip, "install"] + reqs, check=3DTrue, verbose=3DTru= e) + await cmd.run([pip, "install"] + reqs, check=3DTrue, verbose=3Darg= s.verbose) =20 # Freeze environment result =3D await cmd.run([pip, "freeze"], verbose=3DFalse, check= =3DTrue) @@ -248,10 +255,11 @@ class SphinxVenv: await cmd.run(["make", "cleandocs"], env=3Denv, check=3DTrue) make =3D ["make"] + args.make_args + ["htmldocs"] =20 - print(f". {bin_dir}/activate") - print(" ".join(make)) - print("deactivate") - await cmd.run(make, env=3Denv, check=3DTrue) + if args.verbose: + print(f". {bin_dir}/activate") + await cmd.run(make, env=3Denv, check=3DTrue, verbose=3DTrue) + if args.verbose: + print("deactivate") =20 end_time =3D time.time() elapsed_time =3D end_time - start_time @@ -264,7 +272,7 @@ class SphinxVenv: =20 self.built_time[ver] =3D f"{hours:02d}:{minutes:02d}:{seconds:= 02d}" =20 - print(f"Finished doc build for Sphinx {ver}. Elapsed time: {se= lf.built_time[ver]}") + cmd.log(f"Finished doc build for Sphinx {ver}. Elapsed time: {= self.built_time[ver]}", verbose=3DTrue) =20 async def run(self, args): """ @@ -272,6 +280,15 @@ class SphinxVenv: on a loop. """ =20 + if args.log: + fp =3D open(args.log, "w", encoding=3D"utf-8") + if not args.verbose: + args.verbose =3D False + else: + fp =3D None + if not args.verbose: + args.verbose =3D True + cur_requirements =3D {} python_bin =3D MINIMAL_PYTHON_VERSION =20 @@ -290,7 +307,7 @@ class SphinxVenv: if cur_ver > args.max_version: break =20 - await self._handle_version(args, cur_ver, cur_requirements, + await self._handle_version(args, fp, cur_ver, cur_requirements, python_bin) =20 if args.make: @@ -299,6 +316,8 @@ class SphinxVenv: for ver, elapsed_time in sorted(self.built_time.items()): print(f"\tSphinx {ver} elapsed time: {elapsed_time}") =20 + if fp: + fp.close() =20 def parse_version(ver_str): """Convert a version string into a tuple.""" @@ -311,7 +330,7 @@ async def main(): =20 parser =3D argparse.ArgumentParser(description=3D"Build docs for diffe= rent sphinx_versions.") =20 - parser.add_argument('-v', '--version', help=3D'Sphinx single version', + parser.add_argument('-V', '--version', help=3D'Sphinx single version', type=3Dparse_version) parser.add_argument('--min-version', "--min", help=3D'Sphinx minimal v= ersion', type=3Dparse_version) @@ -328,6 +347,11 @@ async def main(): parser.add_argument('-i', '--wait-input', help=3D'Wait for an enter before going to the next= version', action=3D'store_true') + parser.add_argument('-v', '--verbose', + help=3D'Verbose all commands', + action=3D'store_true') + parser.add_argument('-l', '--log', + help=3D'Log command output on a file') =20 args =3D parser.parse_args() =20 --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 AAAF67261F; Sun, 22 Jun 2025 06:02:51 +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=1750572171; cv=none; b=Zx+/WuVRYbVQFxbMi5D51za03p4FmqDe6wAwA0m9mUSDwKSLNBanm/wNt+2odOKw9u7HGOKXCz1wBbhW5Ztr3QzhNW4WF0+5nkrGJ/K3m/jlIfaIqAOFaHQ9PPC5ujBH8mo87iXdC+mNSFSvU6NVoMJru4bqEhv7Zr5cJoCKs9w= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572171; c=relaxed/simple; bh=XYACLriiJLRgjgNmojKmyTGCkYgpJcwpU+eU2NamY1k=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=SxXPBrdGWO3Ab/CkUlA05V/ScczGgJ4oNfkOaf9FnF0jcgqnCMGwKv9CjUrs5s9PI23LQwzovyBruW+8Sy+H7KgQPxAHD11Gw0ODQKt5Hj3P+iCvfrx0limWGm4w42N7hLbrIs+gjyeJhPHQHVkllfwWSfDPdJZFElPNt3pSySQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=vNbuyRdh; 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="vNbuyRdh" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 401C0C4CEF7; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=XYACLriiJLRgjgNmojKmyTGCkYgpJcwpU+eU2NamY1k=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=vNbuyRdhoLRNLBa2ogwke77FpfYi10NMj4WYonoZs8xLPZzs28inpwVkjzcY2I3Uh 26Do9uye9/jKoLcMGTlFcfhRN66tVlXtcau20oDz1tge6B2zIJw9N8dk4yI40SHzbs qGHdnRGdgyCccnst7bybKFGFybijwOCwqufRf5aeeCLHP/YFKPENRTNieGLoNFRvD3 5XZ3ke1Hra2uxo44CEAhhYac81pV6KFo1xXw3EmWOJW7LOk4utnAFWKg6o3JRjwoyA f6DUTB3MLXQGgjQETF7fCDNzwASBnUtaRibxi66eohkULdIWgFhrqT98g1uFpVhy9W 5cow6zXUFyxfQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o2O-1oQ0; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v3 06/15] scripts: test_doc_build.py: better adjust to python version Date: Sun, 22 Jun 2025 08:02:35 +0200 Message-ID: <32cb41c543293bbbab5fcb15f8a0aefac040e3a9.1750571906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" Very old versions of Sphinx require older versions of python. The original script assumes that a python3.9 exec exists, but this may not be the case. Relax python requirements. Signed-off-by: Mauro Carvalho Chehab --- scripts/test_doc_build.py | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/scripts/test_doc_build.py b/scripts/test_doc_build.py index 5b9eb2c0bf01..129c2862065c 100755 --- a/scripts/test_doc_build.py +++ b/scripts/test_doc_build.py @@ -12,15 +12,28 @@ and optionally test the build. import argparse import asyncio import os.path +import shutil import sys import time import subprocess =20 -# Minimal python version supported by the building system -MINIMAL_PYTHON_VERSION =3D "python3.9" +# Minimal python version supported by the building system. =20 -# Starting from 8.0.2, Python 3.9 becomes too old -PYTHON_VER_CHANGES =3D {(8, 0, 2): "python3"} +PYTHON =3D os.path.basename(sys.executable) + +min_python_bin =3D None + +for i in range(9, 13): + p =3D f"python3.{i}" + if shutil.which(p): + min_python_bin =3D p + break + +if not min_python_bin: + min_python_bin =3D PYTHON + +# Starting from 8.0, Python 3.9 is not supported anymore. +PYTHON_VER_CHANGES =3D {(8, 0, 2): PYTHON} =20 # Sphinx versions to be installed and their incremental requirements SPHINX_REQUIREMENTS =3D { @@ -290,7 +303,7 @@ class SphinxVenv: args.verbose =3D True =20 cur_requirements =3D {} - python_bin =3D MINIMAL_PYTHON_VERSION + python_bin =3D min_python_bin =20 for cur_ver, new_reqs in SPHINX_REQUIREMENTS.items(): cur_requirements.update(new_reqs) --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 AC0B18248C; Sun, 22 Jun 2025 06:02:51 +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=1750572171; cv=none; b=SZwDXxdnE9JWX+cgo2TWSTi7j3vjOPlGnJZkmf6lmtGPdTW/yH7m2bPEdA09RXzC1LBHVSB6BNVmdvBhoiP7UtZUjTOEeQvf5R3Ug6bD9FcaX/gM5qXz/dhXjVdn4F313EAwSnDgdsDd8i019z2uq+3YpdkJ7C+j5AANqZQM+zg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572171; c=relaxed/simple; bh=JuIEICGnpDYmiVcGm/h58xaHAndEpsJueWYoYVCqMQs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=qNXe/kDjymHnB3BN/AuTAIjGB2vSVZ6W7t924bnRaWnJVFRZmYONs7TxSJQqsHMkZ1P/qZEBkkhn6FWYjc9Ykm2kB8EeT8o7YGQP/uPdd0yXk4MmjPEwJmeiMwkAoH0mBvrsuGXbDkjvPZvbIPLCL+NUcK9MiCsFQ8K7/ReFlDA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Wz7DYtGH; 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="Wz7DYtGH" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3B4F0C4CEF6; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=JuIEICGnpDYmiVcGm/h58xaHAndEpsJueWYoYVCqMQs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Wz7DYtGHc12KGIUgWMzNxb9mI5AOcskq0yqDO0Igtyp3RqktuNBFXxbL7QrP0BOQX MLL7VPimqHqxDyYXjPCbNjv4z5+5T0K/9OSc6eg6f1PJEWB2m/x8BOPWkXSPi0Xb8A TLtMQuxHPgIMmZ7NEU7PxvdhnS2gcTdILuExlGgpZVtpsXIjS5xuQSll3EtHFT1tl6 yri49fpWJEkXukpl5cx3LMXJMoSr9KjTY1dxX8fmXV6I0JPbwJnO0Iv39+qTcMAOXN zlXR2aZvQIT9nHsTbFvVvTqHB33cJYqMhNHKh+fh2siBRDphrU0Enj2t8ukstKvP6K psh2wVFzL6wWA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o2S-1vlL; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v3 07/15] scripts: test_doc_build.py: improve dependency list Date: Sun, 22 Jun 2025 08:02:36 +0200 Message-ID: <433aeefb4ac9edbd62494334ac07bc1307387d40.1750571906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" Change the dependency list to ensure that: - all docutils versions are covered; - provide an explanation about the dependencies; - set a better minimal requirement for 3.4.3. Signed-off-by: Mauro Carvalho Chehab --- scripts/test_doc_build.py | 68 ++++++++++++++++++++++++++++----------- 1 file changed, 50 insertions(+), 18 deletions(-) diff --git a/scripts/test_doc_build.py b/scripts/test_doc_build.py index 129c2862065c..087b8c476f05 100755 --- a/scripts/test_doc_build.py +++ b/scripts/test_doc_build.py @@ -37,70 +37,102 @@ PYTHON_VER_CHANGES =3D {(8, 0, 2): PYTHON} =20 # Sphinx versions to be installed and their incremental requirements SPHINX_REQUIREMENTS =3D { + # Oldest versions we support for each package required by Sphinx 3.4.3 (3, 4, 3): { + "docutils": "0.16", + "alabaster": "0.7.12", + "babel": "2.8.0", + "certifi": "2020.6.20", + "docutils": "0.16", + "idna": "2.10", + "imagesize": "1.2.0", + "Jinja2": "2.11.2", + "MarkupSafe": "1.1.1", + "packaging": "20.4", + "Pygments": "2.6.1", + "PyYAML": "5.1", + "requests": "2.24.0", + "snowballstemmer": "2.0.0", + "sphinxcontrib-applehelp": "1.0.2", + "sphinxcontrib-devhelp": "1.0.2", + "sphinxcontrib-htmlhelp": "1.0.3", + "sphinxcontrib-jsmath": "1.0.1", + "sphinxcontrib-qthelp": "1.0.3", + "sphinxcontrib-serializinghtml": "1.1.4", + "urllib3": "1.25.9", + }, + + # Update package dependencies to a more modern base. The goal here + # is to avoid to many incremental changes for the next entries + (3, 5, 4): { "alabaster": "0.7.13", "babel": "2.17.0", "certifi": "2025.6.15", - "charset-normalizer": "3.4.2", - "docutils": "0.15", "idna": "3.10", "imagesize": "1.4.1", "Jinja2": "3.0.3", "MarkupSafe": "2.0", "packaging": "25.0", "Pygments": "2.19.1", - "PyYAML": "5.1", "requests": "2.32.4", "snowballstemmer": "3.0.1", "sphinxcontrib-applehelp": "1.0.4", - "sphinxcontrib-devhelp": "1.0.2", "sphinxcontrib-htmlhelp": "2.0.1", - "sphinxcontrib-jsmath": "1.0.1", - "sphinxcontrib-qthelp": "1.0.3", "sphinxcontrib-serializinghtml": "1.1.5", - "urllib3": "2.4.0", }, - (3, 5, 4): {}, + + # Starting from here, ensure all docutils versions are covered with + # supported Sphinx versions. Other packages are upgraded only when + # required by pip (4, 0, 3): { - "docutils": "0.17.1", + "docutils": "0.17", "PyYAML": "5.1", }, - (4, 1, 2): {}, - (4, 3, 2): {}, + (4, 1, 2): { + }, + (4, 3, 2): { + }, (4, 4, 0): {}, (4, 5, 0): {}, (5, 0, 2): {}, (5, 1, 1): {}, (5, 2, 3): { + "docutils": "0.17.1", "Jinja2": "3.1.2", "MarkupSafe": "2.0", "PyYAML": "5.3.1", }, - (5, 3, 0): { - "docutils": "0.18.1", - "PyYAML": "5.3.1", + (5, 3, 0): {}, + (6, 0, 1): { + "docutils": "0.18", }, - (6, 0, 1): {}, (6, 1, 3): {}, (6, 2, 1): { + "docutils": "0.18.1", "PyYAML": "5.4.1", }, - (7, 0, 1): {}, + (7, 0, 1): { + }, (7, 1, 2): {}, (7, 2, 3): { + "docutils": "0.19", "PyYAML": "6.0.1", "sphinxcontrib-serializinghtml": "1.1.9", }, (7, 3, 7): { + "docutils": "0.20", "alabaster": "0.7.14", "PyYAML": "6.0.1", }, (7, 4, 7): { - "docutils": "0.20", + "docutils": "0.21", "PyYAML": "6.0.1", }, - (8, 0, 2): {}, + (8, 0, 2): { + "docutils": "0.21.1", + }, (8, 1, 3): { + "docutils": "0.21.2", "PyYAML": "6.0.1", "sphinxcontrib-applehelp": "1.0.7", "sphinxcontrib-devhelp": "1.0.6", --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 E4D8818DB0D; Sun, 22 Jun 2025 06:02:51 +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=1750572172; cv=none; b=Jg0teteQp76lftMDhUNnsVqLLJ2OwLDSr5wkqZgv+zdIgDgtHARHVge2UxAUlP8Y8eVCvk/VNMOa/GtyupL9EJoTjHnxVA0bmMYS5R5WGyqAE46eJhGGSS81RhsoCzXmvHa955r42guqHJoYkIQ+7hnGkdBmc1BxlPPqGr0g6Vs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572172; c=relaxed/simple; bh=oiyShiLy6Ub+4Mg4ssKBBXxMfSoqaxymRvpCFzMMomw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=WyYwuQ8JnbcOwzxU5C1SNEj/Ywf7r9WphO7sPDqb8FHmiaLEC68J53TuraIV4+jo6zqhlT2id5TyG10/N7HLsQBODZOGOjqosqBnAKc+RqpsBGP3OB6KF9dUYOo7RPkMY9WTpSpAG52vc5M2js++ByYTmkzdo29F+lhfrVpkl5I= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=PYWLXDkD; 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="PYWLXDkD" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4DBBEC4CEF9; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=oiyShiLy6Ub+4Mg4ssKBBXxMfSoqaxymRvpCFzMMomw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PYWLXDkD97MZypYFkQjCNd/buPQ3+OqNPHDxoIg1ga1bFQcuBbOftQxcqpsdXaApl E1Ez0l4sCq6dfY6+8k2Q/Ncf6ikSHwgkVMEDq+Ou412EOSHQx93iXeqL2Cej6q8YeX 2xZJzI0mCDlHKKTtx6AH5VRr3ykyx6rwo5ORHWXaX7L/b0oQDjsW0cHclJ8/IgPWJE jcEnEbwIxg6WwtURsyFPSjoWPmzCm/r/oDBbEnl8uIfpAFumwMNaosETS1pAwCfBtQ KWFj+EifRyEhZfd5cZRDZQWKA475s0HHlm7FBoYmbXxEhD+yTbGGfEqbwMsDQBiBoi Dt8TUSTcB7fFw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o2W-22dr; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v3 08/15] scripts: test_doc_build.py: improve cmd.log logic Date: Sun, 22 Jun 2025 08:02:37 +0200 Message-ID: <2436f37ab7945673f26bcfc94c10e6e76b93c2d8.1750571906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" Simplify the logic which handles with new lines. Signed-off-by: Mauro Carvalho Chehab --- scripts/test_doc_build.py | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/scripts/test_doc_build.py b/scripts/test_doc_build.py index 087b8c476f05..7ea6add48f9a 100755 --- a/scripts/test_doc_build.py +++ b/scripts/test_doc_build.py @@ -157,14 +157,16 @@ class AsyncCommands: self.fp =3D fp =20 def log(self, out, verbose, is_info=3DTrue): + out =3D out.removesuffix('\n') + if verbose: if is_info: - print(out.rstrip("\n")) + print(out) else: - print(out.rstrip("\n"), file=3Dsys.stderr) + print(out, file=3Dsys.stderr) =20 if self.fp: - self.fp.write(out.rstrip("\n") + "\n") + self.fp.write(out + "\n") =20 async def _read(self, stream, verbose, is_info): """Ancillary routine to capture while displaying""" @@ -301,10 +303,10 @@ class SphinxVenv: make =3D ["make"] + args.make_args + ["htmldocs"] =20 if args.verbose: - print(f". {bin_dir}/activate") + cmd.log(f". {bin_dir}/activate", verbose=3DTrue) await cmd.run(make, env=3Denv, check=3DTrue, verbose=3DTrue) if args.verbose: - print("deactivate") + cmd.log("deactivate", verbose=3DTrue) =20 end_time =3D time.time() elapsed_time =3D end_time - start_time @@ -356,10 +358,11 @@ class SphinxVenv: python_bin) =20 if args.make: - print() - print("Summary:") + cmd =3D AsyncCommands(fp) + cmd.log("\nSummary:", verbose=3DTrue) for ver, elapsed_time in sorted(self.built_time.items()): - print(f"\tSphinx {ver} elapsed time: {elapsed_time}") + cmd.log(f"\tSphinx {ver} elapsed time: {elapsed_time}", + verbose=3DTrue) =20 if fp: fp.close() --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 F11A618F2DF; Sun, 22 Jun 2025 06:02:51 +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=1750572172; cv=none; b=G8gMJS7BHpI76jqmatbPd4q8tOB/+v/J+FS2Gr8igKuAriORmxzVCnSJ9/0sdfJZOwhfsykIR/wHVZOym4WreNgzFfY6dEVJIzPs+kgMuJvx8CNGVSwseN8eBDuIyA/J4EuifWrYG8W1Z2aOplQyiX4nKd6KJvMSa1PPpqNGra0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572172; c=relaxed/simple; bh=N4TflgJ9aQP1rQhRd2JGn9NUFXUJr9Aceg88ArqyFIs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Y6xEHFz5LqDVRCpPKuMXValNoNvTkX2x/rK91LLf0zHEnrUDOPOmtw8twRGcV8rvxqT5dMnmALX7pFSB+NT3n5nDp/9hEZN2FVV2IfSa9jO0uryU52T+ki0i/ffGoMee/01ape42sY9l2mhJcpy5GGHSInfWP7VYpxdDBDLXSfE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=eHQIpVXh; 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="eHQIpVXh" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 45CCEC4CEF3; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=N4TflgJ9aQP1rQhRd2JGn9NUFXUJr9Aceg88ArqyFIs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=eHQIpVXhXSV54M2kunZXLs1WOHELHaXg0RuIxM6GjUb9BK3WWYyJab+h2qjeHQNmb VjyiStHq9rcYYONZCq99PXGgkmSuIT8NUvrVEqPsUhyQQwO129KVsrGNsh5rVfLsr1 7AFs/xj6ArddXoW9GY6KIdFDR5S/gy2KtV7e7tYRUUe96Al0QteIv6pliPjCDzAhyE rw0p0ohp8nzUxVzF4Xk/GE3AgpSp+VFCnAHUs4UBlCFKkj+ETFK/c9Ye3p8bmz/gKT 8sX7XzLyPV2pTNFME+sqMMbxWxcjuPQPg8MmJ+hJhDJjVqaL/aTLDJIafjYmt3M0X2 eLVhvujDgY+Rw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o2a-29yY; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v3 09/15] scripts: test_doc_build.py: make the script smarter Date: Sun, 22 Jun 2025 08:02:38 +0200 Message-ID: X-Mailer: git-send-email 2.49.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" Most of the time, testing the full range of supported Sphinx version is a waste of time and resources. Instead, the best is to focus at the versions that are actually shipped by major distros. For it to work properly, we need to adjust the requirements for them to start from first patch for each distro after the minimal supported one. The requirements were re-adjusted to avoid build breakages related to version incompatibilities. Such builds were tested with: ./scripts/test_doc_build.py -m -a "SPHINXOPTS=3D-j8" "SPHINXDIRS=3Dnetwork= ing netlink/specs" --full Change the logic to pick by default only such versions, adding another parameter to do a comprehensive test. While here, improve the script documentation to make it easier to be used. Signed-off-by: Mauro Carvalho Chehab --- scripts/test_doc_build.py | 156 ++++++++++++++++++++++++++------------ 1 file changed, 106 insertions(+), 50 deletions(-) diff --git a/scripts/test_doc_build.py b/scripts/test_doc_build.py index 7ea6add48f9a..5e905a350bd0 100755 --- a/scripts/test_doc_build.py +++ b/scripts/test_doc_build.py @@ -33,7 +33,19 @@ if not min_python_bin: min_python_bin =3D PYTHON =20 # Starting from 8.0, Python 3.9 is not supported anymore. -PYTHON_VER_CHANGES =3D {(8, 0, 2): PYTHON} +PYTHON_VER_CHANGES =3D {(8, 0, 0): PYTHON} + +DEFAULT_VERSIONS_TO_TEST =3D [ + (3, 4, 3), # Minimal supported version + (5, 3, 0), # CentOS Stream 9 / AlmaLinux 9 + (6, 1, 1), # Debian 12 + (7, 2, 1), # openSUSE Leap 15.6 + (7, 2, 6), # Ubuntu 24.04 LTS + (7, 4, 7), # Ubuntu 24.10 + (7, 3, 0), # openSUSE Tumbleweed + (8, 1, 3), # Fedora 42 + (8, 2, 3) # Latest version - covers rolling distros +] =20 # Sphinx versions to be installed and their incremental requirements SPHINX_REQUIREMENTS =3D { @@ -64,82 +76,87 @@ SPHINX_REQUIREMENTS =3D { =20 # Update package dependencies to a more modern base. The goal here # is to avoid to many incremental changes for the next entries - (3, 5, 4): { + (3, 5, 0): { "alabaster": "0.7.13", "babel": "2.17.0", "certifi": "2025.6.15", "idna": "3.10", "imagesize": "1.4.1", - "Jinja2": "3.0.3", - "MarkupSafe": "2.0", "packaging": "25.0", - "Pygments": "2.19.1", + "Pygments": "2.8.1", "requests": "2.32.4", "snowballstemmer": "3.0.1", "sphinxcontrib-applehelp": "1.0.4", "sphinxcontrib-htmlhelp": "2.0.1", "sphinxcontrib-serializinghtml": "1.1.5", + "urllib3": "2.0.0", }, =20 # Starting from here, ensure all docutils versions are covered with # supported Sphinx versions. Other packages are upgraded only when # required by pip - (4, 0, 3): { + (4, 0, 0): { + "PyYAML": "5.1", + }, + (4, 1, 0): { "docutils": "0.17", - "PyYAML": "5.1", - }, - (4, 1, 2): { - }, - (4, 3, 2): { + "Pygments": "2.19.1", + "Jinja2": "3.0.3", + "MarkupSafe": "2.0", }, + (4, 3, 0): {}, (4, 4, 0): {}, - (4, 5, 0): {}, - (5, 0, 2): {}, - (5, 1, 1): {}, - (5, 2, 3): { + (4, 5, 0): { "docutils": "0.17.1", + }, + (5, 0, 0): {}, + (5, 1, 0): {}, + (5, 2, 0): { + "docutils": "0.18", "Jinja2": "3.1.2", "MarkupSafe": "2.0", "PyYAML": "5.3.1", }, - (5, 3, 0): {}, - (6, 0, 1): { - "docutils": "0.18", - }, - (6, 1, 3): {}, - (6, 2, 1): { + (5, 3, 0): { "docutils": "0.18.1", + }, + (6, 0, 0): {}, + (6, 1, 0): {}, + (6, 2, 0): { "PyYAML": "5.4.1", }, - (7, 0, 1): { - }, - (7, 1, 2): {}, - (7, 2, 3): { + (7, 0, 0): {}, + (7, 1, 0): {}, + (7, 2, 0): { "docutils": "0.19", "PyYAML": "6.0.1", "sphinxcontrib-serializinghtml": "1.1.9", }, - (7, 3, 7): { + (7, 2, 6): { "docutils": "0.20", + }, + (7, 3, 0): { "alabaster": "0.7.14", "PyYAML": "6.0.1", + "tomli": "2.0.1", }, - (7, 4, 7): { + (7, 4, 0): { + "docutils": "0.20.1", + "PyYAML": "6.0.1", + }, + (8, 0, 0): { "docutils": "0.21", - "PyYAML": "6.0.1", }, - (8, 0, 2): { + (8, 1, 0): { "docutils": "0.21.1", - }, - (8, 1, 3): { - "docutils": "0.21.2", "PyYAML": "6.0.1", "sphinxcontrib-applehelp": "1.0.7", "sphinxcontrib-devhelp": "1.0.6", "sphinxcontrib-htmlhelp": "2.0.6", "sphinxcontrib-qthelp": "1.0.6", }, - (8, 2, 3): { + (8, 2, 0): { + "docutils": "0.21.2", "PyYAML": "6.0.1", "sphinxcontrib-serializinghtml": "1.1.9", }, @@ -339,13 +356,19 @@ class SphinxVenv: cur_requirements =3D {} python_bin =3D min_python_bin =20 - for cur_ver, new_reqs in SPHINX_REQUIREMENTS.items(): - cur_requirements.update(new_reqs) + vers =3D set(SPHINX_REQUIREMENTS.keys()) | set(args.versions) + + for cur_ver in sorted(vers): + if cur_ver in SPHINX_REQUIREMENTS: + new_reqs =3D SPHINX_REQUIREMENTS[cur_ver] + cur_requirements.update(new_reqs) =20 if cur_ver in PYTHON_VER_CHANGES: # pylint: disable= =3DR1715 - python_bin =3D PYTHON_VER_CHANGES[cur_ver] =20 + if cur_ver not in args.versions: + continue + if args.min_version: if cur_ver < args.min_version: continue @@ -373,12 +396,52 @@ def parse_version(ver_str): return tuple(map(int, ver_str.split("."))) =20 =20 +DEFAULT_VERS =3D " - " +DEFAULT_VERS +=3D "\n - ".join(map(lambda v: f"{v[0]}.{v[1]}.{v[2]}", + DEFAULT_VERSIONS_TO_TEST)) + +SCRIPT =3D os.path.relpath(__file__) + +DESCRIPTION =3D f""" +This tool allows creating Python virtual environments for different +Sphinx versions that are supported by the Linux Kernel build system. + +Besides creating the virtual environment, it can also test building +the documentation using "make htmldocs". + +If called without "--versions" argument, it covers the versions shipped +on major distros, plus the lowest supported version: + +{DEFAULT_VERS} + +A typical usage is to run: + + {SCRIPT} -m -l sphinx_builds.log + +This will create one virtual env for the default version set and do a +full htmldocs build for each version, creating a log file with the +excecuted commands on it. + +NOTE: The build time can be very long, specially on old versions. Also, th= ere +is a known bug with Sphinx version 6.0.x: each subprocess uses a lot of +memory. That, together with "-jauto" may cause OOM killer to cause +failures at the doc generation. To minimize the risk, you may use the +"-a" command line parameter to constrain the built directories and/or +reduce the number of threads from "-jauto" to, for instance, "-j4": + + {SCRIPT} -m -V 6.0.1 -a "SPHINXDIRS=3Dprocess" "SPHINXOPTS=3D'-j4'" + +""" + + async def main(): """Main program""" =20 - parser =3D argparse.ArgumentParser(description=3D"Build docs for diffe= rent sphinx_versions.") + parser =3D argparse.ArgumentParser(description=3DDESCRIPTION, + formatter_class=3Dargparse.RawDescrip= tionHelpFormatter) =20 - parser.add_argument('-V', '--version', help=3D'Sphinx single version', + parser.add_argument('-V', '--versions', help=3D'Sphinx versions to tes= t', + nargs=3D"*", default=3DDEFAULT_VERSIONS_TO_TEST, type=3Dparse_version) parser.add_argument('--min-version', "--min", help=3D'Sphinx minimal v= ersion', type=3Dparse_version) @@ -392,6 +455,9 @@ async def main(): parser.add_argument('-m', '--make', help=3D'Make documentation', action=3D'store_true') + parser.add_argument('-f', '--full', + help=3D'Add all (major,minor,latest_patch) version= to the version list', + action=3D'store_true') parser.add_argument('-i', '--wait-input', help=3D'Wait for an enter before going to the next= version', action=3D'store_true') @@ -406,20 +472,10 @@ async def main(): if not args.make_args: args.make_args =3D [] =20 - if args.version: - if args.min_version or args.max_version: - sys.exit("Use either --version or --min-version/--max-version") - else: - args.min_version =3D args.version - args.max_version =3D args.version - sphinx_versions =3D sorted(list(SPHINX_REQUIREMENTS.keys())) =20 - if not args.min_version: - args.min_version =3D sphinx_versions[0] - - if not args.max_version: - args.max_version =3D sphinx_versions[-1] + if args.full: + args.versions +=3D list(SPHINX_REQUIREMENTS.keys()) =20 venv =3D SphinxVenv() await venv.run(args) --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 E4DF618DB24; Sun, 22 Jun 2025 06:02:51 +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=1750572172; cv=none; b=VahG2xuAOy8eqfkj1eiYslbzXqZWRBr6ZwNYvBjkhJ7XK8rw9SF4o7LK38BPf4pu77yZq1ZrBqnV+T8Errdhlhjn4ViTX4DYTQdVZsAjCEF9SdKBSJT8/pEZBgfuCuwdzskCbkVdXh4bjQpYnEbu7wzxzSe6FwEUwEX8BYgRWZA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572172; c=relaxed/simple; bh=xKHdi1MzGV/x00/8kd5tjimHShTBiCS8QJzsV6mUa0Y=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=hDb2+C9VxqrJxMS4Ri/xwHjPl0eCGRkbnxen/t3QQDpg+6C6nFZZDDnuoM69TFpUjLWAZjKykSUh7Pqu0Al4T0t0WsKWcs6pM0EQqPsswI/bT/B3s22IAHsiUmSn1P0mryVi10Op5R8951MCC0JYcFIjNqaGh6fWVQBuOHOgoZA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=hUgC2q06; 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="hUgC2q06" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4792EC4CEF8; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=xKHdi1MzGV/x00/8kd5tjimHShTBiCS8QJzsV6mUa0Y=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=hUgC2q06W3kAb8jjG2HN3me0Fz6uDl2l/9Eqmp7m7WmjaYQyOqITJ5n7o6zEN6MCh Admu6iW5i/o25jZHQ3YBGqcM9ZgbE2IyL2rziLDwO8xGiQHxOJHFRdkDlga00RyUiq OqV1wtboAn8eRSots4Emuml32KP0i0N3/93y9TBCdUVb9GQyp+k9eWbDsOJ9TAKxvu goBWjdrZtjpHiWerFcjjBDM4Vb+ilts61onkrh5JVo7fxkQ6ugCPjD6HC//gezUkl+ xfypyhIx8IH+nYrO5WQ7DbJLGP+odcnieU2pQlRLYRBDEaq72ehwuRJ4cGRoylVtMw K98Vxz1zrX2vA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o2e-2GsQ; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v3 10/15] scripts: sphinx-pre-install: properly handle SPHINXBUILD Date: Sun, 22 Jun 2025 08:02:39 +0200 Message-ID: X-Mailer: git-send-email 2.49.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" Currently, the script ignores SPHINXBUILD, making it useless. As we're about to use on another script, fix support for it. Signed-off-by: Mauro Carvalho Chehab --- scripts/sphinx-pre-install | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index ad9945ccb0cf..2a311ed00179 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -245,6 +245,10 @@ sub check_missing_tex($) =20 sub get_sphinx_fname() { + if ($ENV{'SPHINXBUILD'}) { + return $ENV{'SPHINXBUILD'}; + } + my $fname =3D "sphinx-build"; return $fname if findprog($fname); =20 --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 CE56B17A319; Sun, 22 Jun 2025 06:02:51 +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=1750572171; cv=none; b=aVbTjNKsrEuk/aSQoLtj8bSbv8TUI3SXldeH2W01niFUjwF/RF4QHsdHeWrz5cY4jBEtdqBGWLJSSo/FRQeCGXzD2s4EEXOYC49aLnzTHXtRkGiaYD8PUyFZLdtJnFQGD7Z8Q5KegW08QWK7AoR02cvSJSMaXjN53EMdti8fqH0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572171; c=relaxed/simple; bh=XM0BRurxei07tGyc7KMfzzV3AHmUgy9wbspSPKa3nxo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=DO9ltz47JiU/w+yU1TZzuS/I+q4lnw6hB8I81Q8NvHN+C4ClgbVe8ZPbgfVJZg1//23+N0yR6wHUxgU4pB3iLk5FkwqGQ5/du6z8AChXiMCpcPN/fYR4xZU1sviKCzpY8NeTNlkrPmK0/7pC+Wyd2u2IsxPxTOViaXjTpUkY1wo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=RsT33Zkc; 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="RsT33Zkc" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4E32BC4CEFB; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=XM0BRurxei07tGyc7KMfzzV3AHmUgy9wbspSPKa3nxo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RsT33Zkc4H6wRI7CB6iSPcF9cwtnImpY4rDabkTXmrw6CGqjLHtd0Is63E07kk5tb b065nL0H/0wypKOi2uDnRe7d46I6o68gtLIE4cEOLEKtuY4q8Nw1lzdiIn0U5h4gfj nyoUDqchwXxdRfffBUgUtrBC+JFJHaM/0TZ3PfP6NbgeuT+juXC8IXXHp5xixvyIty 9TS0w6/jC0qQZqtz7r/Y1g06F0WM7kbfXhyf5x8DVHvZtXAq0eV0c8w64mXkxjXIBP FOgOW/pPEIEIVYzXGW0eckb9j4qRHCbaLiyJAEFQfjl8sI0jY+GNnYtwgMQtqdvkt+ a80ZE/tR8Ir9A== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o2i-2OKT; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v3 11/15] scripts: sphinx-pre-install: fix release detection for Fedora Date: Sun, 22 Jun 2025 08:02:40 +0200 Message-ID: X-Mailer: git-send-email 2.49.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" Fedora distros are now identified as: Fedora Linux 42 Fix the way script detects it. Signed-off-by: Mauro Carvalho Chehab --- scripts/sphinx-pre-install | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 2a311ed00179..3f8d6925e896 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -413,7 +413,7 @@ sub give_redhat_hints() my $old =3D 0; my $rel; my $noto_sans_redhat =3D "google-noto-sans-cjk-ttc-fonts"; - $rel =3D $1 if ($system_release =3D~ /release\s+(\d+)/); + $rel =3D $1 if ($system_release =3D~ /(release|Linux)\s+(\d+)/); =20 if (!($system_release =3D~ /Fedora/)) { $map{"virtualenv"} =3D "python-virtualenv"; --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 36B13194A6C; Sun, 22 Jun 2025 06:02:51 +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=1750572172; cv=none; b=fZiSmGM9JBhZ7gQTSU76FBwUrnkMqtZ7h5AaL/22p6C4Coeugf2IkvTKeK7pQZN4PYnVAjytg1ctNva5+oH/zU1he0cYHZKolq9raPCHtds31i4HknGS6FNLKZkN65gdwGpbb8jjR0ex3UP30hLPOQVLnLeynm0+5rRoVwpZhLM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572172; c=relaxed/simple; bh=y8LZ0fXrmuwyAMvRo91pI8wsN2CZiBu2VRksVUBmRVg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=SrY02Jeetmbo17ktE+82eW6ZZZxNEfBHQY4NJv7gUgUwTh5haQ1bts6WZaNgNX2/yrBsJVEjx07l+YIU1ZtDzhya7y4xO6NX3krqOPzYm+bitUowt/tNU4JFUMhXmGl1AyRLepaTUkSzfRoG7QFXuf8cDrhovAO2S3+NTsv91yk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Vw3so/bP; 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="Vw3so/bP" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 63FF2C113D0; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=y8LZ0fXrmuwyAMvRo91pI8wsN2CZiBu2VRksVUBmRVg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Vw3so/bPwOEhGwLSFZuCspsu2IlRTVqzLtH+76kGm0jeLk64auMFqQzTXAnDeknxW WbZB8oOUKHFyd1Pt9ch2D2PtbhvJuT3hfUdt4UCIHVz/G6zYIWS3fXqQ5H0sbRUzSx fhSNumtA+gFfRMWmwEKx9xaadN96qFiMnY1nn8goZkWvn7DZz7WzLkhb68RY7f+R/s 4PWV3l5iNu1qEaMj3FG65jWGF2KWTdZTENhiUV8Rl4hWFx4nQpuCQ6AfzeSlMTfRBC LKmt2l+U6H/drBj0v1oawSSjskWlTIxDp1bpvrnMU3FHdvDIC7b1r7N3nrOvN/XNFD f1czd59OoyWiA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o2m-2Va8; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v3 12/15] scripts: test_doc_build.py: regroup and rename arguments Date: Sun, 22 Jun 2025 08:02:41 +0200 Message-ID: X-Mailer: git-send-email 2.49.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" The script now have lots or arguments. Better organize and name them, for it to be a little bit more intuitive. Signed-off-by: Mauro Carvalho Chehab --- scripts/test_doc_build.py | 95 +++++++++++++++++++++++++-------------- 1 file changed, 61 insertions(+), 34 deletions(-) diff --git a/scripts/test_doc_build.py b/scripts/test_doc_build.py index 5e905a350bd0..47b4606569f9 100755 --- a/scripts/test_doc_build.py +++ b/scripts/test_doc_build.py @@ -269,7 +269,7 @@ class SphinxVenv: =20 ver =3D ".".join(map(str, cur_ver)) =20 - if not self.first_run and args.wait_input and args.make: + if not self.first_run and args.wait_input and args.build: ret =3D input("Press Enter to continue or 'a' to abort: ").str= ip().lower() if ret =3D=3D "a": print("Aborted.") @@ -300,11 +300,11 @@ class SphinxVenv: result =3D await cmd.run([pip, "freeze"], verbose=3DFalse, check= =3DTrue) =20 # Pip install succeeded. Write requirements file - if args.write: + if args.req_file: with open(req_file, "w", encoding=3D"utf-8") as fp: fp.write(result.stdout) =20 - if args.make: + if args.build: start_time =3D time.time() =20 # Prepare a venv environment @@ -317,7 +317,16 @@ class SphinxVenv: =20 # Test doc build await cmd.run(["make", "cleandocs"], env=3Denv, check=3DTrue) - make =3D ["make"] + args.make_args + ["htmldocs"] + make =3D ["make"] + + if args.output: + sphinx_build =3D os.path.realpath(f"{bin_dir}/sphinx-build= ") + make +=3D [f"O=3D{args.output}", f"SPHINXBUILD=3D{sphinx_b= uild}"] + + if args.make_args: + make +=3D args.make_args + + make +=3D args.targets =20 if args.verbose: cmd.log(f". {bin_dir}/activate", verbose=3DTrue) @@ -380,7 +389,7 @@ class SphinxVenv: await self._handle_version(args, fp, cur_ver, cur_requirements, python_bin) =20 - if args.make: + if args.build: cmd =3D AsyncCommands(fp) cmd.log("\nSummary:", verbose=3DTrue) for ver, elapsed_time in sorted(self.built_time.items()): @@ -407,7 +416,7 @@ This tool allows creating Python virtual environments f= or different Sphinx versions that are supported by the Linux Kernel build system. =20 Besides creating the virtual environment, it can also test building -the documentation using "make htmldocs". +the documentation using "make htmldocs" (and/or other doc targets). =20 If called without "--versions" argument, it covers the versions shipped on major distros, plus the lowest supported version: @@ -418,8 +427,8 @@ A typical usage is to run: =20 {SCRIPT} -m -l sphinx_builds.log =20 -This will create one virtual env for the default version set and do a -full htmldocs build for each version, creating a log file with the +This will create one virtual env for the default version set and run +"make htmldocs" for each version, creating a log file with the excecuted commands on it. =20 NOTE: The build time can be very long, specially on old versions. Also, th= ere @@ -433,6 +442,15 @@ reduce the number of threads from "-jauto" to, for ins= tance, "-j4": =20 """ =20 +MAKE_TARGETS =3D [ + "htmldocs", + "texinfodocs", + "infodocs", + "latexdocs", + "pdfdocs", + "epubdocs", + "xmldocs", +] =20 async def main(): """Main program""" @@ -440,32 +458,41 @@ async def main(): parser =3D argparse.ArgumentParser(description=3DDESCRIPTION, formatter_class=3Dargparse.RawDescrip= tionHelpFormatter) =20 - parser.add_argument('-V', '--versions', help=3D'Sphinx versions to tes= t', - nargs=3D"*", default=3DDEFAULT_VERSIONS_TO_TEST, - type=3Dparse_version) - parser.add_argument('--min-version', "--min", help=3D'Sphinx minimal v= ersion', - type=3Dparse_version) - parser.add_argument('--max-version', "--max", help=3D'Sphinx maximum v= ersion', - type=3Dparse_version) - parser.add_argument('-a', '--make_args', - help=3D'extra arguments for make htmldocs, like SP= HINXDIRS=3Dnetlink/specs', - nargs=3D"*") - parser.add_argument('-w', '--write', help=3D'write a requirements.txt = file', - action=3D'store_true') - parser.add_argument('-m', '--make', - help=3D'Make documentation', - action=3D'store_true') - parser.add_argument('-f', '--full', - help=3D'Add all (major,minor,latest_patch) version= to the version list', - action=3D'store_true') - parser.add_argument('-i', '--wait-input', - help=3D'Wait for an enter before going to the next= version', - action=3D'store_true') - parser.add_argument('-v', '--verbose', - help=3D'Verbose all commands', - action=3D'store_true') - parser.add_argument('-l', '--log', - help=3D'Log command output on a file') + ver_group =3D parser.add_argument_group("Version range options") + + ver_group.add_argument('-V', '--versions', nargs=3D"*", + default=3DDEFAULT_VERSIONS_TO_TEST,type=3Dparse= _version, + help=3D'Sphinx versions to test') + ver_group.add_argument('--min-version', "--min", type=3Dparse_version, + help=3D'Sphinx minimal version') + ver_group.add_argument('--max-version', "--max", type=3Dparse_version, + help=3D'Sphinx maximum version') + ver_group.add_argument('-f', '--full', action=3D'store_true', + help=3D'Add all Sphinx (major,minor) supported = versions to the version range') + + build_group =3D parser.add_argument_group("Build options") + + build_group.add_argument('-b', '--build', action=3D'store_true', + help=3D'Build documentation') + build_group.add_argument('-a', '--make-args', nargs=3D"*", + help=3D'extra arguments for make, like SPHINX= DIRS=3Dnetlink/specs', + ) + build_group.add_argument('-t', '--targets', nargs=3D"+", choices=3DMAK= E_TARGETS, + default=3D[MAKE_TARGETS[0]], + help=3D"make build targets. Default: htmldocs= .") + build_group.add_argument("-o", '--output', + help=3D"output directory for the make O=3DOUT= PUT") + + other_group =3D parser.add_argument_group("Other options") + + other_group.add_argument('-r', '--req-file', action=3D'store_true', + help=3D'write a requirements.txt file') + other_group.add_argument('-l', '--log', + help=3D'Log command output on a file') + other_group.add_argument('-v', '--verbose', action=3D'store_true', + help=3D'Verbose all commands') + other_group.add_argument('-i', '--wait-input', action=3D'store_true', + help=3D'Wait for an enter before going to the next= version') =20 args =3D parser.parse_args() =20 --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 DC0DD18A93F; Sun, 22 Jun 2025 06:02:51 +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=1750572172; cv=none; b=cedPW3n2utj/96sgP6OE872iVhbD26K1IwXei8yIygRwNayu8EelTnU03sssOw+q5oWlxucWlWR00eEUkoNLI0n9976FLrBayVCii+EyXn1LWPTEegWtIR7pDnVLpaICNH4zS6xRKNcY8h0jY995ezwucxk520O3iuQyQc8SHZg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572172; c=relaxed/simple; bh=3yI0hd++pTAVk6UlNj1uaAE4va43OAIfWkR3JnQPolk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Se7VumUIjlYA6grzVYCE5U00+Ln6yD74noRdxpr9SuB067RkmpxVwRWEl9azdoE4FsSPzWsSWAmUIb2wAf88W6qTmK67sNcidxY2GZaHbS4U1rbMcKfWdXkvbRx70CTU6ZNa1WXcde573aaLvyY51JmSSAqEPTNKB3ejsG4kd4U= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=PtnFKHB/; 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="PtnFKHB/" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 66186C4AF0C; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=3yI0hd++pTAVk6UlNj1uaAE4va43OAIfWkR3JnQPolk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PtnFKHB/W7NTw9PGTMng2N4qb+pAy0jragCYcBjAxyJ3iJPPwIMFC7BHvCZYor37c +RLdABfzQp/FoBARjDcPsGicErpKR0BwKgvaPSUD6xOw/PijG2gjDcwHSvJcPYE92s e9nQ5MW+6ijxI4tKDyfBuqXc70WdEn5KNsvodRLMg3K7tdfDsgEvAIa5cBA9R6FIQG 0J0G96OqC5I8gBnuYog4t1EacK70NF+0wtvKQSjgDAFuc9AIX039A8AUia4V0H0EZe UEJojV1Cn2wr+RyUrIMoqsccwoNurGOf4bZkoXE1duZiLy7jL8wNx6rtUoPobN3ZwQ sY0UqdOqmX9EQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o2q-2cbr; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , Randy Dunlap , linux-kernel@vger.kernel.org Subject: [PATCH v3 13/15] docs: sphinx: add a file with the requirements for lowest version Date: Sun, 22 Jun 2025 08:02:42 +0200 Message-ID: X-Mailer: git-send-email 2.49.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" Those days, it is hard to install a virtual env that would build docs with Sphinx 3.4.3, as even python 3.13 is not compatible anymore with it. /usr/bin/python3.9 -m venv sphinx_3.4.3 . sphinx_3.4.3/bin/activate pip install -r Documentation/sphinx/min_requirements.txt Signed-off-by: Mauro Carvalho Chehab --- Documentation/doc-guide/sphinx.rst | 23 +++++++++++++++++++++++ Documentation/sphinx/min_requirements.txt | 10 ++++++++++ 2 files changed, 33 insertions(+) create mode 100644 Documentation/sphinx/min_requirements.txt diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/s= phinx.rst index 5a91df105141..607589592bfb 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -131,6 +131,29 @@ It supports two optional parameters: ``--no-virtualenv`` Use OS packaging for Sphinx instead of Python virtual environment. =20 +Installing Sphinx Minimal Version +--------------------------------- + +When changing Sphinx build system, it is important to ensure that +the minimal version will still be supported. Nowadays, it is +becoming harder to do that on modern distributions, as it is not +possible to install with Python 3.13 and above. + +Testing with the lowest supported Python version as defined at +Documentation/process/changes.rst can be done by creating +a venv with it with, and install minimal requirements with:: + + /usr/bin/python3.9 -m venv sphinx_min + . sphinx_min/bin/activate + pip install -r Documentation/sphinx/min_requirements.txt + +A more comprehensive test can be done by using: + + scripts/test_doc_build.py + +Such script create one Python venv per supported version, +optionally building documentation for a range of Sphinx versions. + =20 Sphinx Build =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D diff --git a/Documentation/sphinx/min_requirements.txt b/Documentation/sphi= nx/min_requirements.txt new file mode 100644 index 000000000000..52d9f27010e8 --- /dev/null +++ b/Documentation/sphinx/min_requirements.txt @@ -0,0 +1,10 @@ +alabaster >=3D0.7,<0.8 +docutils>=3D0.15,<0.18 +jinja2>=3D2.3,<3.1 +PyYAML>=3D5.1,<6.1 +Sphinx=3D=3D3.4.3 +sphinxcontrib-applehelp=3D=3D1.0.2 +sphinxcontrib-devhelp=3D=3D1.0.1 +sphinxcontrib-htmlhelp=3D=3D1.0.3 +sphinxcontrib-qthelp=3D=3D1.0.2 +sphinxcontrib-serializinghtml=3D=3D1.1.4 --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 23121192D83; Sun, 22 Jun 2025 06:02:52 +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=1750572172; cv=none; b=arQAFMyss1T2DJRN91U7kHrmdjzQAJq9ZzkJ2w1r6gHyxoWQ519fnZKNkn28kDV9jUqElOzuInw+1LGHfWx9KfkNtyLYWn8Kd0qS+kgcACt7tJ71j6iUZrqCUoRMfOe/ZUoHCXUvCWovo6DOBxGLo0ppxNA1hwvPb48pnSSxpq4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572172; c=relaxed/simple; bh=Qmmi8Gl3DNYe5BW7ZlNJcJLLiiwo57HKRdyY+HHucDU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=CZ53IHmHnwUNvMBYivPoEjAS9gHfzj5Qyc7/SdrKmKr6v+Hby1+CfrCAVA1jt3JkmEOXoLSmw1Ly4TWZ1vQ1jv5lXYXSYet5pThnLxH5cR8wCEOHvtwDLNotawBQpJH0yEWdKyqyHE3r71RZUz2f4TrubPE4TWm4vjb4zenvO5A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=KMev0JB1; 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="KMev0JB1" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 640D8C4AF0B; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=Qmmi8Gl3DNYe5BW7ZlNJcJLLiiwo57HKRdyY+HHucDU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KMev0JB1yOEUS+FT+ncqpKlQ4tljbqhbzZo+qlqEICpIrkq/rxCYzvcFb6wxVb1PP mMYJkSQLypNhL296lDB82zwcG0zVIPMhaHPRLe+rhrVRmKM+G13OBhIWV8SzGnc9Jl UG/+c8VTHyuSoPycjCQvT04IvLkNElAR4uWqUAzEpYkm5G3ICWa3nY93ZzmkZ60Uy2 4dW75kHrr3wxJEWOJMUZEc3T+KZhC0MEUgTv0HK1hb1BkKw2+KM9nOMrt5hHVTxFZy khlvGBJTTYKM4gsCxuYHyeh1qDdq/64gKt7/g1uPTTWRmTK1nYtCFP8m+PLfa9hgS7 331EaP7kGIDlA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o2u-2jl5; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v3 14/15] docs: conf.py: several coding style fixes Date: Sun, 22 Jun 2025 08:02:43 +0200 Message-ID: <063c106d96e86ca30c3266f7819f30b7247881ed.1750571906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab conf.py is missing a SPDX header and doesn't really have a proper python coding style. It also has an obsolete commented LaTeX syntax that doesn't work anymore. Clean it up a little bit with some help from autolints and manual adjustments. Signed-off-by: Mauro Carvalho Chehab --- Documentation/conf.py | 351 +++++++++++++++++++++--------------------- 1 file changed, 172 insertions(+), 179 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 91ce2b1c33cc..700516238d3f 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -1,24 +1,28 @@ -# -*- coding: utf-8 -*- -# -# The Linux Kernel documentation build configuration file, created by -# sphinx-quickstart on Fri Feb 12 13:51:46 2016. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. +# SPDX-License-Identifier: GPL-2.0-only +# pylint: disable=3DC0103,C0209 + +""" +The Linux Kernel documentation build configuration file. +""" =20 -import sys import os -import sphinx import shutil +import sys + +import sphinx + +# If extensions (or modules to document with autodoc) are in another direc= tory, +# add these directories to sys.path here. If the directory is relative to = the +# documentation root, use os.path.abspath to make it absolute, like shown = here. +sys.path.insert(0, os.path.abspath("sphinx")) + +from load_config import loadConfig # pylint: disable=3DC0413= ,E0401 + +# Minimal supported version +needs_sphinx =3D "3.4.3" =20 # Get Sphinx version -major, minor, patch =3D sphinx.version_info[:3] +major, minor, patch =3D sphinx.version_info[:3] # pylint: disable= =3DI1101 =20 # Include_patterns were added on Sphinx 5.1 if (major < 5) or (major =3D=3D 5 and minor < 1): @@ -26,23 +30,22 @@ if (major < 5) or (major =3D=3D 5 and minor < 1): else: has_include_patterns =3D True # Include patterns that don't contain directory names, in glob format - include_patterns =3D ['**.rst'] + include_patterns =3D ["**.rst"] =20 # Location of Documentation/ directory -doctree =3D os.path.abspath('.') +doctree =3D os.path.abspath(".") =20 # Exclude of patterns that don't contain directory names, in glob format. exclude_patterns =3D [] =20 # List of patterns that contain directory names in glob format. dyn_include_patterns =3D [] -dyn_exclude_patterns =3D ['output'] +dyn_exclude_patterns =3D ["output"] =20 # Properly handle include/exclude patterns # ---------------------------------------- =20 def update_patterns(app, config): - """ On Sphinx, all directories are relative to what it is passed as SOURCEDIR parameter for sphinx-build. Due to that, all patterns @@ -53,15 +56,12 @@ def update_patterns(app, config): exclude relative patterns that start with "../". """ =20 - sourcedir =3D app.srcdir # full path to the source directory - builddir =3D os.environ.get("BUILDDIR") - # setup include_patterns dynamically if has_include_patterns: for p in dyn_include_patterns: full =3D os.path.join(doctree, p) =20 - rel_path =3D os.path.relpath(full, start =3D app.srcdir) + rel_path =3D os.path.relpath(full, start=3Dapp.srcdir) if rel_path.startswith("../"): continue =20 @@ -71,15 +71,17 @@ def update_patterns(app, config): for p in dyn_exclude_patterns: full =3D os.path.join(doctree, p) =20 - rel_path =3D os.path.relpath(full, start =3D app.srcdir) + rel_path =3D os.path.relpath(full, start=3Dapp.srcdir) if rel_path.startswith("../"): continue =20 config.exclude_patterns.append(rel_path) =20 + # helper # ------ =20 + def have_command(cmd): """Search ``cmd`` in the ``PATH`` environment. =20 @@ -88,24 +90,23 @@ def have_command(cmd): """ return shutil.which(cmd) is not None =20 -# If extensions (or modules to document with autodoc) are in another direc= tory, -# add these directories to sys.path here. If the directory is relative to = the -# documentation root, use os.path.abspath to make it absolute, like shown = here. -sys.path.insert(0, os.path.abspath('sphinx')) -from load_config import loadConfig =20 # -- General configuration ------------------------------------------------ =20 -# If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx =3D '3.4.3' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions =3D ['kerneldoc', 'rstFlatTable', 'kernel_include', - 'kfigure', 'sphinx.ext.ifconfig', 'automarkup', - 'maintainers_include', 'sphinx.ext.autosectionlabel', - 'kernel_abi', 'kernel_feat', 'translations'] +# Add any Sphinx extensions in alphabetic order +extensions =3D [ + "automarkup", + "kernel_abi", + "kerneldoc", + "kernel_feat", + "kernel_include", + "kfigure", + "maintainers_include", + "rstFlatTable", + "sphinx.ext.autosectionlabel", + "sphinx.ext.ifconfig", + "translations", +] =20 # Since Sphinx version 3, the C function parser is more pedantic with rega= rds # to type checking. Due to that, having macros at c:function cause problem= s. @@ -180,28 +181,28 @@ autosectionlabel_maxdepth =3D 2 # Load math renderer: # For html builder, load imgmath only when its dependencies are met. # mathjax is the default math renderer since Sphinx 1.8. -have_latex =3D have_command('latex') -have_dvipng =3D have_command('dvipng') +have_latex =3D have_command("latex") +have_dvipng =3D have_command("dvipng") load_imgmath =3D have_latex and have_dvipng =20 # Respect SPHINX_IMGMATH (for html docs only) -if 'SPHINX_IMGMATH' in os.environ: - env_sphinx_imgmath =3D os.environ['SPHINX_IMGMATH'] - if 'yes' in env_sphinx_imgmath: +if "SPHINX_IMGMATH" in os.environ: + env_sphinx_imgmath =3D os.environ["SPHINX_IMGMATH"] + if "yes" in env_sphinx_imgmath: load_imgmath =3D True - elif 'no' in env_sphinx_imgmath: + elif "no" in env_sphinx_imgmath: load_imgmath =3D False else: sys.stderr.write("Unknown env SPHINX_IMGMATH=3D%s ignored.\n" % en= v_sphinx_imgmath) =20 if load_imgmath: extensions.append("sphinx.ext.imgmath") - math_renderer =3D 'imgmath' + math_renderer =3D "imgmath" else: - math_renderer =3D 'mathjax' + math_renderer =3D "mathjax" =20 # Add any paths that contain templates here, relative to this directory. -templates_path =3D ['sphinx/templates'] +templates_path =3D ["sphinx/templates"] =20 # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: @@ -209,15 +210,15 @@ templates_path =3D ['sphinx/templates'] source_suffix =3D '.rst' =20 # The encoding of source files. -#source_encoding =3D 'utf-8-sig' +# source_encoding =3D 'utf-8-sig' =20 # The master toctree document. -master_doc =3D 'index' +master_doc =3D "index" =20 # General information about the project. -project =3D 'The Linux Kernel' -copyright =3D 'The kernel development community' -author =3D 'The kernel development community' +project =3D "The Linux Kernel" +copyright =3D "The kernel development community" # pylint: disable= =3DW0622 +author =3D "The kernel development community" =20 # The version info for the project you're documenting, acts as replacement= for # |version| and |release|, also used in various other places throughout the @@ -232,82 +233,86 @@ author =3D 'The kernel development community' try: makefile_version =3D None makefile_patchlevel =3D None - for line in open('../Makefile'): - key, val =3D [x.strip() for x in line.split('=3D', 2)] - if key =3D=3D 'VERSION': - makefile_version =3D val - elif key =3D=3D 'PATCHLEVEL': - makefile_patchlevel =3D val - if makefile_version and makefile_patchlevel: - break -except: + with open("../Makefile", encoding=3D"utf=3D8") as fp: + for line in fp: + key, val =3D [x.strip() for x in line.split("=3D", 2)] + if key =3D=3D "VERSION": + makefile_version =3D val + elif key =3D=3D "PATCHLEVEL": + makefile_patchlevel =3D val + if makefile_version and makefile_patchlevel: + break +except Exception: pass finally: if makefile_version and makefile_patchlevel: - version =3D release =3D makefile_version + '.' + makefile_patchlev= el + version =3D release =3D makefile_version + "." + makefile_patchlev= el else: version =3D release =3D "unknown version" =20 -# -# HACK: there seems to be no easy way for us to get at the version and -# release information passed in from the makefile...so go pawing through t= he -# command-line options and find it for ourselves. -# + def get_cline_version(): - c_version =3D c_release =3D '' + """ + HACK: There seems to be no easy way for us to get at the version and + release information passed in from the makefile...so go pawing through= the + command-line options and find it for ourselves. + """ + + c_version =3D c_release =3D "" for arg in sys.argv: - if arg.startswith('version=3D'): + if arg.startswith("version=3D"): c_version =3D arg[8:] - elif arg.startswith('release=3D'): + elif arg.startswith("release=3D"): c_release =3D arg[8:] if c_version: if c_release: - return c_version + '-' + c_release + return c_version + "-" + c_release return c_version - return version # Whatever we came up with before + return version # Whatever we came up with before + =20 # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language =3D 'en' +language =3D "en" =20 # There are two options for replacing |today|: either, you set today to so= me # non-false value, then it is used: -#today =3D '' +# today =3D '' # Else, today_fmt is used as the format for a strftime call. -#today_fmt =3D '%B %d, %Y' +# today_fmt =3D '%B %d, %Y' =20 # The reST default role (used for this markup: `text`) to use for all # documents. -#default_role =3D None +# default_role =3D None =20 # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses =3D True +# add_function_parentheses =3D True =20 # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -#add_module_names =3D True +# add_module_names =3D True =20 # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors =3D False +# show_authors =3D False =20 # The name of the Pygments (syntax highlighting) style to use. -pygments_style =3D 'sphinx' +pygments_style =3D "sphinx" =20 # A list of ignored prefixes for module index sorting. -#modindex_common_prefix =3D [] +# modindex_common_prefix =3D [] =20 # If true, keep warnings as "system message" paragraphs in the built docum= ents. -#keep_warnings =3D False +# keep_warnings =3D False =20 # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos =3D False =20 -primary_domain =3D 'c' -highlight_language =3D 'none' +primary_domain =3D "c" +highlight_language =3D "none" =20 # -- Options for HTML output ---------------------------------------------- =20 @@ -315,43 +320,45 @@ highlight_language =3D 'none' # a list of builtin themes. =20 # Default theme -html_theme =3D 'alabaster' +html_theme =3D "alabaster" html_css_files =3D [] =20 if "DOCS_THEME" in os.environ: html_theme =3D os.environ["DOCS_THEME"] =20 -if html_theme =3D=3D 'sphinx_rtd_theme' or html_theme =3D=3D 'sphinx_rtd_d= ark_mode': +if html_theme in ["sphinx_rtd_theme", "sphinx_rtd_dark_mode"]: # Read the Docs theme try: import sphinx_rtd_theme + html_theme_path =3D [sphinx_rtd_theme.get_html_theme_path()] =20 # Add any paths that contain custom static files (such as style sh= eets) here, # relative to this directory. They are copied after the builtin st= atic files, # so a file named "default.css" will overwrite the builtin "defaul= t.css". html_css_files =3D [ - 'theme_overrides.css', + "theme_overrides.css", ] =20 # Read the Docs dark mode override theme - if html_theme =3D=3D 'sphinx_rtd_dark_mode': + if html_theme =3D=3D "sphinx_rtd_dark_mode": try: - import sphinx_rtd_dark_mode - extensions.append('sphinx_rtd_dark_mode') + import sphinx_rtd_dark_mode # pylint: disable= =3DW0611 + + extensions.append("sphinx_rtd_dark_mode") except ImportError: - html_theme =3D=3D 'sphinx_rtd_theme' + html_theme =3D "sphinx_rtd_theme" =20 - if html_theme =3D=3D 'sphinx_rtd_theme': - # Add color-specific RTD normal mode - html_css_files.append('theme_rtd_colors.css') + if html_theme =3D=3D "sphinx_rtd_theme": + # Add color-specific RTD normal mode + html_css_files.append("theme_rtd_colors.css") =20 html_theme_options =3D { - 'navigation_depth': -1, + "navigation_depth": -1, } =20 except ImportError: - html_theme =3D 'alabaster' + html_theme =3D "alabaster" =20 if "DOCS_CSS" in os.environ: css =3D os.environ["DOCS_CSS"].split(" ") @@ -359,14 +366,14 @@ if "DOCS_CSS" in os.environ: for l in css: html_css_files.append(l) =20 -if html_theme =3D=3D 'alabaster': +if html_theme =3D=3D "alabaster": html_theme_options =3D { - 'description': get_cline_version(), - 'page_width': '65em', - 'sidebar_width': '15em', - 'fixed_sidebar': 'true', - 'font_size': 'inherit', - 'font_family': 'serif', + "description": get_cline_version(), + "page_width": "65em", + "sidebar_width": "15em", + "fixed_sidebar": "true", + "font_size": "inherit", + "font_family": "serif", } =20 sys.stderr.write("Using %s theme\n" % html_theme) @@ -374,104 +381,79 @@ sys.stderr.write("Using %s theme\n" % html_theme) # Add any paths that contain custom static files (such as style sheets) he= re, # relative to this directory. They are copied after the builtin static fil= es, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path =3D ['sphinx-static'] +html_static_path =3D ["sphinx-static"] =20 # If true, Docutils "smart quotes" will be used to convert quotes and dash= es # to typographically correct entities. However, conversion of "--" to "= =E2=80=94" # is not always what we want, so enable only quotes. -smartquotes_action =3D 'q' +smartquotes_action =3D "q" =20 # Custom sidebar templates, maps document names to template names. # Note that the RTD theme ignores this -html_sidebars =3D { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelin= k.html']} +html_sidebars =3D {"**": ["searchbox.html", + "kernel-toc.html", + "sourcelink.html"]} =20 # about.html is available for alabaster theme. Add it at the front. -if html_theme =3D=3D 'alabaster': - html_sidebars['**'].insert(0, 'about.html') +if html_theme =3D=3D "alabaster": + html_sidebars["**"].insert(0, "about.html") =20 # The name of an image file (relative to this directory) to place at the t= op # of the sidebar. -html_logo =3D 'images/logo.svg' +html_logo =3D "images/logo.svg" =20 # Output file base name for HTML help builder. -htmlhelp_basename =3D 'TheLinuxKerneldoc' +htmlhelp_basename =3D "TheLinuxKerneldoc" =20 # -- Options for LaTeX output --------------------------------------------- =20 latex_elements =3D { # The paper size ('letterpaper' or 'a4paper'). - 'papersize': 'a4paper', - + "papersize": "a4paper", # The font size ('10pt', '11pt' or '12pt'). - 'pointsize': '11pt', - + "pointsize": "11pt", # Latex figure (float) alignment - #'figure_align': 'htbp', - + # 'figure_align': 'htbp', # Don't mangle with UTF-8 chars - 'inputenc': '', - 'utf8extra': '', - + "inputenc": "", + "utf8extra": "", # Set document margins - 'sphinxsetup': ''' + "sphinxsetup": """ hmargin=3D0.5in, vmargin=3D1in, parsedliteralwraps=3Dtrue, verbatimhintsturnover=3Dfalse, - ''', - + """, # # Some of our authors are fond of deep nesting; tell latex to # cope. # - 'maxlistdepth': '10', - + "maxlistdepth": "10", # For CJK One-half spacing, need to be in front of hyperref - 'extrapackages': r'\usepackage{setspace}', - + "extrapackages": r"\usepackage{setspace}", # Additional stuff for the LaTeX preamble. - 'preamble': ''' + "preamble": """ % Use some font with UTF-8 support with XeLaTeX \\usepackage{fontspec} \\setsansfont{DejaVu Sans} \\setromanfont{DejaVu Serif} \\setmonofont{DejaVu Sans Mono} - ''', + """, } =20 # Load kerneldoc specific LaTeX settings -latex_elements['preamble'] +=3D ''' +latex_elements["preamble"] +=3D """ % Load kerneldoc specific LaTeX settings - \\input{kerneldoc-preamble.sty} -''' - -# With Sphinx 1.6, it is possible to change the Bg color directly -# by using: -# \definecolor{sphinxnoteBgColor}{RGB}{204,255,255} -# \definecolor{sphinxwarningBgColor}{RGB}{255,204,204} -# \definecolor{sphinxattentionBgColor}{RGB}{255,255,204} -# \definecolor{sphinximportantBgColor}{RGB}{192,255,204} -# -# However, it require to use sphinx heavy box with: -# -# \renewenvironment{sphinxlightbox} {% -# \\begin{sphinxheavybox} -# } -# \\end{sphinxheavybox} -# } -# -# Unfortunately, the implementation is buggy: if a note is inside a -# table, it isn't displayed well. So, for now, let's use boring -# black and white notes. + \\input{kerneldoc-preamble.sty} +""" =20 # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). # Sorted in alphabetical order -latex_documents =3D [ -] +latex_documents =3D [] =20 # Add all other index files from Documentation/ subdirectories -for fn in os.listdir('.'): +for fn in os.listdir("."): doc =3D os.path.join(fn, "index") if os.path.exists(doc + ".rst"): has =3D False @@ -480,34 +462,39 @@ for fn in os.listdir('.'): has =3D True break if not has: - latex_documents.append((doc, fn + '.tex', - 'Linux %s Documentation' % fn.capitali= ze(), - 'The kernel development community', - 'manual')) + latex_documents.append( + ( + doc, + fn + ".tex", + "Linux %s Documentation" % fn.capitalize(), + "The kernel development community", + "manual", + ) + ) =20 # The name of an image file (relative to this directory) to place at the t= op of # the title page. -#latex_logo =3D None +# latex_logo =3D None =20 # For "manual" documents, if this is true, then toplevel headings are part= s, # not chapters. -#latex_use_parts =3D False +# latex_use_parts =3D False =20 # If true, show page references after internal links. -#latex_show_pagerefs =3D False +# latex_show_pagerefs =3D False =20 # If true, show URL addresses after external links. -#latex_show_urls =3D False +# latex_show_urls =3D False =20 # Documents to append as an appendix to all manuals. -#latex_appendices =3D [] +# latex_appendices =3D [] =20 # If false, no module index is generated. -#latex_domain_indices =3D True +# latex_domain_indices =3D True =20 # Additional LaTeX stuff to be copied to build directory latex_additional_files =3D [ - 'sphinx/kerneldoc-preamble.sty', + "sphinx/kerneldoc-preamble.sty", ] =20 =20 @@ -516,12 +503,11 @@ latex_additional_files =3D [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages =3D [ - (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation', - [author], 1) + (master_doc, "thelinuxkernel", "The Linux Kernel Documentation", [auth= or], 1) ] =20 # If true, show URL addresses after external links. -#man_show_urls =3D False +# man_show_urls =3D False =20 =20 # -- Options for Texinfo output ------------------------------------------- @@ -529,11 +515,15 @@ man_pages =3D [ # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) -texinfo_documents =3D [ - (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation', - author, 'TheLinuxKernel', 'One line description of project.', - 'Miscellaneous'), -] +texinfo_documents =3D [( + master_doc, + "TheLinuxKernel", + "The Linux Kernel Documentation", + author, + "TheLinuxKernel", + "One line description of project.", + "Miscellaneous", + ),] =20 # -- Options for Epub output ---------------------------------------------- =20 @@ -544,9 +534,9 @@ epub_publisher =3D author epub_copyright =3D copyright =20 # A list of files that should not be packed into the epub file. -epub_exclude_files =3D ['search.html'] +epub_exclude_files =3D ["search.html"] =20 -#=3D=3D=3D=3D=3D=3D=3D +# =3D=3D=3D=3D=3D=3D=3D # rst2pdf # # Grouping the document tree into PDF files. List of tuples @@ -558,14 +548,14 @@ epub_exclude_files =3D ['search.html'] # multiple PDF files here actually tries to get the cross-referencing right # *between* PDF files. pdf_documents =3D [ - ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'), + ("kernel-documentation", "Kernel", "Kernel", "J. Random Bozo"), ] =20 # kernel-doc extension configuration for running Sphinx directly (e.g. by = Read # the Docs). In a normal build, these are supplied from the Makefile via c= ommand # line arguments. -kerneldoc_bin =3D '../scripts/kernel-doc.py' -kerneldoc_srctree =3D '..' +kerneldoc_bin =3D "../scripts/kernel-doc.py" +kerneldoc_srctree =3D ".." =20 # ------------------------------------------------------------------------= ------ # Since loadConfig overwrites settings from the global namespace, it has t= o be @@ -573,5 +563,8 @@ kerneldoc_srctree =3D '..' # ------------------------------------------------------------------------= ------ loadConfig(globals()) =20 + def setup(app): + """Patterns need to be updated at init time on older Sphinx versions""" + app.connect('config-inited', update_patterns) --=20 2.49.0 From nobody Thu Oct 9 01:16:06 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 F23C818FC91; Sun, 22 Jun 2025 06:02:51 +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=1750572172; cv=none; b=Wc3SsWVjDGalomAp3XX/a0WTBGvzvQ0SWDH0SRPIwGnXb8Q+WUBO6CWNXRZixXBoCaqHWMnRSkELMTK6639jFhI+8kDrnaTehQLXZWFBBe0mCW1Zmg7d+Znrn6lECAr/Rir0NJmxNF5Tnctm60ZowyAeK18xmoVFKLDrRHrVBgg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750572172; c=relaxed/simple; bh=Md1fJUprA8k5FhxpqjtZ0V+UUyFkBLNA2WvebeFh5mE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=pjyrwV2mow2qiAycbhB/ZZnYxeiOYhb+PJl5zcgYlMWZTAg29Q+PzewwvPd7tm/zA1CWcSATPcBOxI0JAjHJpaM0F9hJ30ikxvbRH7WzNnHtMta1uSMaJz8EURHB7SnVjIH2+QHpRvz4mwCBSuZX6BN/2vESOOUq1BSZ/Pfg56c= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=mQArGjLa; 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="mQArGjLa" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6D315C4AF0D; Sun, 22 Jun 2025 06:02:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750572171; bh=Md1fJUprA8k5FhxpqjtZ0V+UUyFkBLNA2WvebeFh5mE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=mQArGjLaaejKQ7qkesr4qR8Ntss0yynvV7KNysq22XhBGiaUrW8GUnps+QHkQ05hU /8LyM0iRdS/9RT1lFY3ERLbn56CZga5AmkkeBlEhqXZcvMesY7mOEJYgDX1cRICTKS Ii//iMqcYP1OvIWbqREDZG1I+xM2sAoG5mFHmrrljlBBSqW/tz7wAxtdBK4Sxi44qi Fy3Q113CqWiH4/i4XpMZkjjPBV4g1OvRC1wd2TU9fFT99u3naLzeqaLC1GJA8KkR8s dS4EZNFMfFVxCxOh6VOXbvcFhMgr6qKImCf8rGW/dmn7zu6uFKJZumggw0dIS33XUZ 5tA/k7v9VVdww== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uTDmz-00000000o2y-2rAM; Sun, 22 Jun 2025 08:02:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v3 15/15] docs: conf.py: Check Sphinx and docutils version Date: Sun, 22 Jun 2025 08:02:44 +0200 Message-ID: <972673b0a5bf5537d47780d6f8e70ae45456e751.1750571906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" As reported by Akira, there were incompatibility issues with Sphinx and docutils with docutils 0.19. There's already a fix for it, but, as there are incompatibility issues with different versions, better to add a check to verify if the combination is supported/tested. After check Sphinx release notes, it seems that the version compatibility is given by: =3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Sphinx Min Docutils Max Docutils Version Version Version ------- ------------ ------------ 3.4.3 >=3D 0.12.0 < 0.18.0 4.0.0 >=3D 0.12.0 < 0.19.0 6.0.0 >=3D 0.18.0 < 0.20.0 7.0.0 >=3D 0.18.1 < 0.21.0 7.2.0 >=3D 0.18.1 < 0.20.0 7.4.0 >=3D 0.18.1 < 0.21.0 8.0.0 >=3D 0.20.0 < 0.22.0 8.2.3 >=3D 0.20.0 < 0.22.0 =3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D For now, add a logic inside conf.py to check the above compatibility list, emitting warnings if the docutils version doesn't match it. This way, when we discover incompatibility issues, we can easily adjust the table. Signed-off-by: Mauro Carvalho Chehab --- Documentation/conf.py | 70 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 67 insertions(+), 3 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 700516238d3f..df99a4d96b58 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -9,7 +9,11 @@ import os import shutil import sys =20 +import docutils import sphinx +from sphinx.util import logging + +logger =3D logging.getLogger(__name__) =20 # If extensions (or modules to document with autodoc) are in another direc= tory, # add these directories to sys.path here. If the directory is relative to = the @@ -21,11 +25,71 @@ from load_config import loadConfig # pyli= nt: disable=3DC0413,E0401 # Minimal supported version needs_sphinx =3D "3.4.3" =20 -# Get Sphinx version -major, minor, patch =3D sphinx.version_info[:3] # pylint: disable= =3DI1101 +# Get Sphinx and docutils versions +sphinx_ver =3D sphinx.version_info[:3] # pylint: disable=3DI1101 +docutils_ver =3D docutils.__version_info__[:3] + +sphinx_ver_str =3D ".".join([str(x) for x in sphinx_ver]) +docutils_ver_str =3D ".".join([str(x) for x in docutils_ver]) + +# Docutils min/max versions. +# The dockutils version check logic is done with: +# ver >=3D min and ver < max +SPHINX_DOCUTILS_VERS =3D { + (3, 4, 3): { + "min": (0, 12, 0), + "max": (0, 18, 0) + }, + (4, 0, 0): { + "min": (0, 12, 0), + "max": (0, 19, 0) + }, + (6, 0, 0): { + "min": (0, 18, 0), + "max": (0, 20, 0) + }, + (7, 0, 0): { + "min": (0, 18, 1), + "max": (0, 21, 0) + }, + (7, 2, 0): { + "min": (0, 18, 1), + "max": (0, 20, 0) + }, + (7, 4, 0): { + "min": (0, 18, 1), + "max": (0, 21, 0) + }, + (8, 0, 0): { + "min": (0, 20, 0), + "max": (0, 22, 0) + }, + (8, 2, 3): { + "min": (0, 20, 0), + "max": (0, 22, 0) + }, +} + +du_min =3D None +du_max =3D None +for sp_ver, doc_vers in SPHINX_DOCUTILS_VERS.items(): + if sp_ver > sphinx_ver: + break + + du_min =3D doc_vers.get("min") + du_max =3D doc_vers.get("max") + +if sphinx_ver > sorted(SPHINX_DOCUTILS_VERS.keys())[-1]: + logger.warning(f"Sphinx version {sphinx_ver_str} is too new and not te= sted. Doc generation may fail") +elif not du_min or not du_max: + logger.warning(f"Sphinx version {sphinx_ver_str} is not tested. Doc ge= neration may fail") +elif docutils_ver < du_min: + logger.warning(f"Docutils {docutils_ver_str} is too old for Sphinx {sp= hinx_ver_str}. Doc generation may fail") +elif docutils_ver >=3D du_max: + logger.warning(f"Docutils {docutils_ver_str} could be too new for Sphi= nx {sphinx_ver_str}. Doc generation may fail") =20 # Include_patterns were added on Sphinx 5.1 -if (major < 5) or (major =3D=3D 5 and minor < 1): +if sphinx_ver < (5, 1, 0): has_include_patterns =3D False else: has_include_patterns =3D True --=20 2.49.0