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 E63791C75E2; Sat, 21 Jun 2025 19:56:00 +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=1750535761; cv=none; b=bDYUKTs3cxHVN9d4YCoShukxYPTaNUxhZEJp/UpYS6cH5wHQt2j1aAOmdTdww8fPUZbnkpnL9+hezOZzUsuL/socfCCVXNM4kIEu4rQ69gJVlsNKc3pMfLt0ftIR5C9niOTgERFj7kx9n92KE2rUvZYYp4Jdn/opXsxFEQJclcQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=JvTI+DF/1Dszyn4T0n7ZKhi6vNtj6FoC1Ae/TMd5FHM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=M5VKi29mLBGazWEsLYhCSZksZENLby9gDAE6VBhu8CmOundjXEOxiEjLjVDlDXbk9pqRJ8RczT1qxJuwMhfvqSweVkqZ7axDsuYkhJDtzuADP1d6r1WkofIKdyRp3YxF8MmUf8qTDd958UUBbyn/Mo0YOUOWT7+vva5ILAQsUsc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=KPUaPay3; 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="KPUaPay3" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9ED81C4AF0B; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535760; bh=JvTI+DF/1Dszyn4T0n7ZKhi6vNtj6FoC1Ae/TMd5FHM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KPUaPay3ElPI3a6f9isa+EFoHAHoP1yEwqgdktcW2n/wXDZzyG8YwRNSSGe8fBlvv XnHOBIK1u0Ydpevjia/IGZv3ZROcDjHtDgmpdGOh8dqBgIv/3+es1Otq5d+Ouc2Jfz NNrwBgLVCaiV/tNJi7+LWdqkiRJLECjQMbYKOT+621h94tA7rXYjgjGd5Y+BfIF+If UhjLP4hZTu4dEa9Hd8clfwg2J9UJ8bRFR6iJL697xRDE69qATaTruCcxIqvUyVMKJ1 GHT1j3fvku65kjCY+jW53+8LaapoRfe8pKNYUmNpP+eQW3E6HPEbrISs25bN8DiXlc bPhGu6DQl40Sg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e3c-2NwE; Sat, 21 Jun 2025 21:55:58 +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 v2 01/15] docs: conf.py: properly handle include and exclude patterns Date: Sat, 21 Jun 2025 21:55:40 +0200 Message-ID: <737b08e891765dc10bd944d4d42f8b1e37b80275.1750535171.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..4ba4ee45e599 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): + + """ + 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 + + app.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 + + app.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('builder-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 E656526FA4C; Sat, 21 Jun 2025 19:56:00 +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=1750535761; cv=none; b=C/ezq5Vmgj54mU3Fj/GcFqQQdRTa9m5iejYHtz+c49WOC3fwmcjmKpZE/1KJ4HczS1dIFOsP9MorQMoy/uiIoWGNxgwUL/viSH43L75UV8diLuwrKgL3dLVAfECq6NH9nmoXjQDebaMTUZG0AdK6bX5tWzNMQ002GQV123XUIeg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=9sv3o8O8M0IyOR5wJkoSEusaPecRlQcEL5SoMo0iJ7A=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=A6fPriBHR4MiOXCPWlsJdgd4ehsdA0D8KBtSIb8rdXKyTPFbq4rM0nNxSNN9BA+158Sa+S7cS7c2OQ9473SFI/Qbk5oTFTHxVNl48RBtCY8d0Ur4aAclfq1bxGg23GDRIKsMTQGGzJ5rd4QSG3h8VtcSfcTxJqFi04R0hVU4MDM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=hdy63fv+; 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="hdy63fv+" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9CE8EC4CEF2; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535760; bh=9sv3o8O8M0IyOR5wJkoSEusaPecRlQcEL5SoMo0iJ7A=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=hdy63fv+uBZEkzeaRx7QEBWeREgt6HEubqnd8S7382ZCpNHgZU+n7MRc1S9pmuJsh /UQ+n0h+QGJWkeB5vDrjHcYCHFt+LSF8CfcZ4CQePWPtTb2amytfhVCx/XnSd4JfRk A19cROT4weSGVyDTs3MQ6VaGRgJzyOLHPearF6J3rU7ySWqAdrPX+0DomYy2SJwfG8 8r7IEmnkDBr1yhu8S//asWe7CEX32aBt/P/ad0wCO7LUaoV0BKFKFaUS2nLhtQUf49 NW42sOl/NCkyLV/Gc7V4xdF8bPKKsvzIMRxkKY1N2p3y0i9KR4QfciXmf2nLtTTVh6 VdVfdTNdXYaZg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e3g-2Upc; Sat, 21 Jun 2025 21:55:58 +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 v2 02/15] docs: Makefile: disable check rules on make cleandocs Date: Sat, 21 Jun 2025 21:55: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" 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 70A20271442; Sat, 21 Jun 2025 19:56:01 +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=1750535761; cv=none; b=uHeAOGQtKKl/Yf68gJffVe+K1fsaHwhzRMDSvH2q1D4CgueFMuidpyL8cI477L1LzqrPdOChZ5oEAWKGysjcZdh18mr7R9Cuge0SOGKH8SPhKUmICeDNK9eP1o3OhVu8kzZpAgl91dcDfZQr7vbXaGsr3Pf4b7uVRxcUCBXYM2c= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=wx0BDvaHpPo9dP1wTRMAhz/5i+/h4gNQceHfFlSoK7g=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=WaNIB1bTuGeqDFgg5qffrATPA5LBcL9k9FZEtzZbclkznnnwzUhQi1rCU4FWgzKhmdwbQ7+etV/u2GHxGhUNMoxFNUtxCktje08Bs8GPh50ZuBkQMZrDnwCr0utbvBEehHdosoUsp0RZHU7tJiy0B+bG3BwkJqv+9w8/ZmkQRvk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Wo72P8NM; 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="Wo72P8NM" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A54FEC4CEF3; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535760; bh=wx0BDvaHpPo9dP1wTRMAhz/5i+/h4gNQceHfFlSoK7g=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Wo72P8NML9fSDBiOqg7Q8/ZKIEgkRZMWfgmN2mC8xxD5frVZNNXOQORHofjU7QFWY GzR5za4Q9246lGGiT+qEU6ASXiG8RdXam7SPdNlUU9eu43Dm9/MzoHfij5YYmTCz4q 67Kf1BG88vvX5bvhC7+fwcxbANTW7tpF9H4VppNCjfWsbhswtf7WXjLwwjFLRXh/ra 3yr0CBacm4ayL/yShin7oCinBWK1GmNP2VVnSFduMCstRaPlSUBiX09riPpzl3rfp7 pVV6Ft5sygSfSvviJDgqQi0Il7leb3VnYQlKzUCPVuvvVJwzrVMg861+BRZkkLuvyx /Yyksai5KIKWg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e3k-2bik; Sat, 21 Jun 2025 21:55:58 +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 v2 03/15] scripts: scripts/test_doc_build.py: add script to test doc build Date: Sat, 21 Jun 2025 21:55:42 +0200 Message-ID: <1858fa581a86a1c684cf1c6044be98d482022251.1750535171.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 7900C271443; Sat, 21 Jun 2025 19:56:01 +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=1750535761; cv=none; b=C2Gtk77VRaa3PZJevV8p/dT09JhRFsI0WWCzd4I6G5p8t//QmKO5ykE/sdkG4syLxeAnXWtuItxXAbgjmOBvVcIu7lKE/0HXtdOKwWIHVyzz3oKu3IiuRB+CQYtKUr1bhJNUa6yHts6QUWaudhXNwpVi9HnCHFW69FNGItZ/cqs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=XT+7KR3Tg4iAhlUU3c6mKrOGy1MIPvbKyEPBCyZpAmw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=H+6DphEkaREz2jTCWTl+RGv9wYyQ2CEb0UkwpuAy8MJUlx4kouPXJ9kYw+mGj1UMW79sqgQydUPYVTLrOVuXsn6rOB8oGQoTaUvXQ0mJ5EM6dvop8RLYhhi0Tofr0qjiOd+uNA/UCiNnubSIbOYRVjedmNlX4sy6LnakVsK3lpc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Mr9b/2tO; 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="Mr9b/2tO" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A7949C4CEF5; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535761; bh=XT+7KR3Tg4iAhlUU3c6mKrOGy1MIPvbKyEPBCyZpAmw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Mr9b/2tONdxjdtQPHr8vCSRa3QhLMe7nFcNBmlW/BSzlQVKiiICG8v3hg/ih/1uD0 /RZ7I0P1SMCIIhXHBK26Q4nyLzWOK9uvbEYLI67eDTxMSxlkL79rhIMjY7FP2vTWRE GlxyuiViNNjjVzOHyiGxU1xMAUPXRqEWwKq2gyRi65wOwfKWGxPsOrYuMW09i5dfQm 2QX87s7Zc0TQwRYZjaS1tqAL6u2bgGYlowDiJvIP3nCoj1aJB+SJPqRxmrztE4eoAI VKjxZrDKUu3xdSE85JkVbl3KposaReH0ogsdDwJk+jnN8JexaQmmPPUQovMFRjK8Xc CZ3JGdYql7xBg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e3o-2inP; Sat, 21 Jun 2025 21:55:58 +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 v2 04/15] scripts: test_doc_build.py: make capture assynchronous Date: Sat, 21 Jun 2025 21:55:43 +0200 Message-ID: <90999a8bd725a32298000aa64d4e1cff1672ae9a.1750535171.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 4730C270ECD; Sat, 21 Jun 2025 19:56:01 +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=1750535761; cv=none; b=YxY5BfOO+Lo2PSMJUSb6PXhReANt/R+LBuuvAJk5Yn9xAydugzTOc5R56/qDq0EWm9TwJT8xIfdjj5tbGngjMyQljPjhQRI1JkWDq7DY/5I10bfDXrsGTt7KjKim8pYorEOqeZ+ZjJi+sBMHwQztkC3p+EQlvqth1lLOXAr55o0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=t6WKKzUZ3jaz/IWeMR8qJbIf2p6B9ADIoUTLRFgr0u0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=HLQLnbxAGdZXgLiZ10Hr790Bx6Q6RXEhYVRUKtZlNggJnlChLmltfYyKOx2cmzKdpCHYr1OM/v8U0ueKrcpwCPF+TsJQaxVhw15rphJBzUd3S4HnTu8Nk+U+fOX+kzE9UD6WIRQMaQFEy+iRe6RnyjUQgMmARBy53rZlixltVcg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=uspxPMDR; 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="uspxPMDR" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 948EAC4CEEF; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535760; bh=t6WKKzUZ3jaz/IWeMR8qJbIf2p6B9ADIoUTLRFgr0u0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=uspxPMDRVQRqzfmTQepswnWdLpN+bdqPPl6RX8VRyni0Sw2UtYkHsnh9/J3j5qn1p NjKqjXu6eJrTLqZn+JvS1XF0ysSYugIS9Qq4nDdS2u9TAps6RBi+Fgp27rnlm4IIUG xCVyHfq+8S7hN1eMZARI9ugMrgL6cLyWcfVFVdEdVABVh7O7+lv4mRRwLsivSHWR1J Wr5okAQBQ7Bznvk1n+07CL32KuwA2ecM9wiz5yb1teLD2jqOlUwfIgKiNARCsBCmby xA+eaoqOdTezVqJCFAuvhDCKox6Qf9AksQ01S9ZzuCu8fNk6NkK+JlTW3+aze3Ppj6 nMe61Sy4Ely6g== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e3s-2pYe; Sat, 21 Jun 2025 21:55:58 +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 v2 05/15] scripts: test_doc_build.py: better control its output Date: Sat, 21 Jun 2025 21:55:44 +0200 Message-ID: <7adea4976165fa2c80e00e02fa2fa3124d27351c.1750535171.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 E6409259C82; Sat, 21 Jun 2025 19:56:00 +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=1750535761; cv=none; b=n00k9+EfRMBuVTL1oCEtX94r2VcBpNEPrwTPlSeboO8Cs8NFl5c/GLpvbTDPvx8RNl5fkP6FcW0oBaCur6de0+2cWsJLa51Rj92aPREgV38okWX79RdjNVnDqLBYBnKoefUyFIZEeLHYDXV0R0IO4aoWoA8Icy9rynXFc/hDYw0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=XYACLriiJLRgjgNmojKmyTGCkYgpJcwpU+eU2NamY1k=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=X2Ni7NpszKjQYyqM6veerheD52qXmBxBv2/Beu3P+ATvaBu3cWlR3RcklYnR/Y67WG50lKUWk5Mvzc3UT+be582ZH5SQDH3G7P2COd4bsTdc4/FHvBNo9mjnGxrhUBXRTfejD1kU6XHaB+Wb3kzw/4e9jxzllepbpH/B+1x1hBc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=oTl/F1lw; 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="oTl/F1lw" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 949C0C4AF09; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535760; bh=XYACLriiJLRgjgNmojKmyTGCkYgpJcwpU+eU2NamY1k=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=oTl/F1lw92gn7j6PvN2MD6wP3QD43u1ljkmRhGc2Tugx7354ISiVB+dL2jTrG+ie0 SVr0MS61LY/Rx6ShNS1aCaMwLJZd1WifeFWdEehuSBttvfGcvIULZL0O5rkEKlkmCK GMoUxTZndkcFRavc46VgrQCR2Tqx96xN6ANDRqC27Ll6Xu4xPp+/xBQxMCiQdXSKeU Mo1Qk6ldqLTNjq+blvBBFL/j/fyuMYkkJLWU98mUu/RcuBmoeaHGEsri3r4jMvGobv GNGhI7IOq7rCmjjrTtWkJQI0otvMW+8fFKvryZQCs7zubKMp0DMHT5vp8mKlMk1kbj YY/vYIHG2+OBQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e3w-2wSV; Sat, 21 Jun 2025 21:55:58 +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 v2 06/15] scripts: test_doc_build.py: better adjust to python version Date: Sat, 21 Jun 2025 21:55:45 +0200 Message-ID: <0d9e86390f0bc443880cafc442466a959c59609f.1750535171.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 1D052270571; Sat, 21 Jun 2025 19:56:01 +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=1750535761; cv=none; b=lii9Z4UudqPFFG3BKcIebfZO/yoJ0uafAuRihomytlBTK7wK38Vdav0p/Ss9D9VSJIxEcoyW5jfXid3ITpiR8weelZvPuTCtMrXqMpadtCsWCxvqjqWLtTQDxdnZtxqz4+lt8nMzd4r0rQ86Vfneze7euEOKyGmOACsgGnxCzHc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=JuIEICGnpDYmiVcGm/h58xaHAndEpsJueWYoYVCqMQs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=MxOTcjmcaBGvGvwOis1ee0/vDsBpMcWQoWLs79wrd8UPJ/svsZT52yGsu0+rBr+kzDKd76H3/WX3+JByWhAcrglHKRwV51QwLhs6YiZz7vRf4e1gvVONEg+P7QVb3Ov9CfMOWVIfhRQRlMu0uUT+dN5ml1FxyTiEZEpLBUTMolQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=DGX/t1w3; 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="DGX/t1w3" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A0EDAC4AF0C; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535760; bh=JuIEICGnpDYmiVcGm/h58xaHAndEpsJueWYoYVCqMQs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=DGX/t1w3KvdxSzPASQUFu9xAAcgqC/5+rZsstgB6LLAHjcuog8BQoZGHc5cMVPlCV 6mphv1zgtfw+7avQykv4kSdLS2hYN4/dSNSV+It5bfECXjw79vi0W2lFAOLlIFcvB1 /tMM9JoEHM7jxkzuVz8cfrCpAAah9i3PVvaxwy2vdszm96oiTm9WSSms7qin6286Yb sFjjNTtD42j0XlHmWxYNS8XifszOOOIpnZN6weJUGjniywKZRJUkGSwvq32gm5mX73 i3sE67HLuanQZEW6j8XEMBP56gqCMxsdXq9mWz11cH9Iq7eLpuAeJRZ01ZRUs6zhg6 5vpyIRH9n2wmA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e40-33EF; Sat, 21 Jun 2025 21:55:58 +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 v2 07/15] scripts: test_doc_build.py: improve dependency list Date: Sat, 21 Jun 2025 21:55:46 +0200 Message-ID: <9eac3b7dab2f59349044c53201d6a71cf06d8df1.1750535171.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 41963270EBB; Sat, 21 Jun 2025 19:56:01 +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=1750535761; cv=none; b=W+/viKaC8dVx2g58QulOav0z/a2iY6mpLCv3wZIPe+UmLWZtV+OcmxcRTvzEpTO4IHk/BpX2mO7gEKxHI+U4vNLIlDgggDxulci4p3bKueBHhVwDxQFFg0H0CotoBhOXTuavpIqbyoFJH1ZnlgQFF4F0GLP4vuE8Puof/Xojd7E= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=oiyShiLy6Ub+4Mg4ssKBBXxMfSoqaxymRvpCFzMMomw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=hebPHuVefkOVDAJ5ikT1AboJ2ETow+6gUmEudHGl39B6QOzxer29GVZF3UndkOElgob7YVoFDpaivf8pnk6mRph1scrFpfLl47H9r1beMPPvtBHdRBM204+Sr3MZC7CBsK7b+iUBx7xLnntNjmQk1SkbA5sK+Pk3UGyuhL25zP4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=L210lewo; 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="L210lewo" Received: by smtp.kernel.org (Postfix) with ESMTPSA id AA56BC4CEF4; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535760; bh=oiyShiLy6Ub+4Mg4ssKBBXxMfSoqaxymRvpCFzMMomw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=L210lewoTx/bkGvcjNi6kCGjARZfGNNhxfm9nfNA14b0iiCRrfZs563PY2peN+EAe WrXV+gb0/+NVub2kiVObZOOWpV+/uxPK6My/j8WdV6ZbErpBXkmG8uvWpMB5VVI/gr Jb3hB2/Qqt2VrbbrwzpX0O9AEfMlrNE0kCfY7qyTur7ySPpN8SjSXtDvhn9tO/0ihO wrjf81tw9DwD3gEgevi+3EuQOnnIlp2P821o5AKHTRacJ5uH0KzxLBT/1YGevT6FcW IE3O5E7hVQBBiwA725BV21NYWE5Oq16mBZeTMnjLnaqL8zplv9GH2GLkhy3Ubar7FP ku6PavIR4hSaA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e44-39j2; Sat, 21 Jun 2025 21:55:58 +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 v2 08/15] scripts: test_doc_build.py: improve cmd.log logic Date: Sat, 21 Jun 2025 21:55:47 +0200 Message-ID: <48078563434a857be8077d9707e539faa70a3521.1750535171.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 4A28A270ED2; Sat, 21 Jun 2025 19:56:01 +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=1750535761; cv=none; b=KtxxNkopIeafqAhn7LWJciCSo/NB0vh571n0aryucfx19xRBKxuKOvgfeCwiU8PUEWtBbOb755goq6pVMrCZD+ju4/Uh0ThlLgKZzeQmv1miAesMRLOBCSwehxFA5r9g+9uvIB/bg0pnn0Sd2pYOMpzHi4AQfnVtqDTGgSJAwk0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=N4TflgJ9aQP1rQhRd2JGn9NUFXUJr9Aceg88ArqyFIs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=ZLMD9rv6J6ZRpgWvniyi6Czl3JVIyKDco0LtrA36AidwEC9gEEdR1C087aBdIhDJiAgxIAvzeEOWZ6ZfzL5+pFxzhMPGvpp/TzZyWeUtPk6w6ZTlqBWthFyz3TwieyeCGWKIrFr3iGCSiRG3BrP82ZjxuShMEh4Tzxy4aCM6P7Q= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Hf32jNQn; 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="Hf32jNQn" Received: by smtp.kernel.org (Postfix) with ESMTPSA id AED42C4AF0D; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535760; bh=N4TflgJ9aQP1rQhRd2JGn9NUFXUJr9Aceg88ArqyFIs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Hf32jNQnnu9Ig+sgCpJZrxK7LFRT7UMYP+i08dGNU5Korgv5vHpOjnGiVmPwBcfMX pHRQw1/UWKx+9GZgLctkadTA355jCjEYDw30+LJcpY1ZNp2YA3q46g66xcHGKPyu9x ii/52eR2v1r3/wKenP74uAk41EnasXcUqv92n0rKBcL59gpVwJCwdpXSxqqimgNSvN rFM8c4BAKSj8f1cLqRmyCsjEGHsP+/SImUWp1CVV2fzV0JGiI0JScJvlH6LmV+xiJ7 Dkl8c3aFDnnqpcDfNoKM6O6puT36gnGotVSLXYP6XvqY9mqp40ZXi1Sl6Ioi1PLJ6J 5rdxtBJtIsuEg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e48-3GbA; Sat, 21 Jun 2025 21:55:58 +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 v2 09/15] scripts: test_doc_build.py: make the script smarter Date: Sat, 21 Jun 2025 21:55:48 +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 E64EC26A0E3; Sat, 21 Jun 2025 19:56:00 +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=1750535761; cv=none; b=tiWUUMWJ6qfMjKNlrsbD76pgL6iSqWcIvQs6VYvgyaocAlDILOpybR5DW/ooiHHsIWNQA1qIURa084Ah1SLbYZFARtC85hPHlIeWB2C7+Cbb085ivd3bE8rztnctfELm2KoAqYfjhSlhz1Fr9hiO0i5+KVpu5+WrUyYxen/vhEU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=xKHdi1MzGV/x00/8kd5tjimHShTBiCS8QJzsV6mUa0Y=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=LqRN1KXQd+DIjA4Pdvh3IRbrIq9J8gG2rUk7bHCtoIdnLnlggqM4c3GKQB0oDRZE2eODbDu8ljC8d+/B+5W8xauRJaUChrjTdVchQKmOaXEgw98wjukslQKkuIdTY1QeXNuGxCmF6qyEDEhz1r3ilmDnC/KkoVQxXOFG6RtAJE0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=RV35sHqH; 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="RV35sHqH" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9A5D7C4CEF0; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535760; bh=xKHdi1MzGV/x00/8kd5tjimHShTBiCS8QJzsV6mUa0Y=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RV35sHqH6ola1xIUhnjFLvaDe7ZSJixw5XXymGgFldOSccq1B8pnA0h+VCGeyKg0N NwUoWDD7svR4FhcOcmOIIPfkyOh8qHoAPtQawVfxWANvn85IohKh8quZyV+F8aVo3G vB4uw4r3UpnvOK6uK9LUQzNbMZ0SkmkLBwo5NT/NGHfiahOy31xJyIvvk6SUsdHTYp QB3VlBh5WnusXi4pekzMn/iIt4LQT+35SznRkwO7bFipVEPqUGQq/c5/7qzpWxhM5N 57CSHe8QgTva0TezM91ouBYEvRJD+CeOPvoejyeGpm6P6UnU0fAye0E7sL6Z8UWOn4 jaUpLTxAXh7Dw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e4C-3NTX; Sat, 21 Jun 2025 21:55:58 +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 v2 10/15] scripts: sphinx-pre-install: properly handle SPHINXBUILD Date: Sat, 21 Jun 2025 21:55:49 +0200 Message-ID: <907016315b18e17b113670f2ea81a927c22dcb80.1750535171.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" 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 3F814270EB2; Sat, 21 Jun 2025 19:56:01 +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=1750535761; cv=none; b=khZGijMlvm/oPG4ScUlOfeyx3ZyMJxTYxnJpDm+4oY30BBujEJn7t6Vw7vuC1yWLMwmvivO/EiE5SFozBQo1ZUBZGZ2qcq1FsRnR2sUT956noD6DKcXQljWKZtMFFty918fko2SlPZBUm17uJ2f/JyBwuUSO6aHqNkqSSa9dhmE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=XM0BRurxei07tGyc7KMfzzV3AHmUgy9wbspSPKa3nxo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=tKRwoMKjU7IgK0+NdwWnW5m7o2ZWHaPFW/EVZykezYISy5y+Sj0mQPuHeMc/iBVP1zpsG9XyMihkK0Ivh9l47EfLFV/o/rpPx8+wgk70n2J6RARXnW4Oakp7X45xEYpCmWcKyTnlHJkyJOBZC5OocoDdYigKff5vz4EJteS25A0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=aFW02x2I; 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="aFW02x2I" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A2FEAC4CEF1; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535760; bh=XM0BRurxei07tGyc7KMfzzV3AHmUgy9wbspSPKa3nxo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=aFW02x2IBj6uZQecVNFsqvwymcOnVg/oNIksMbgO/HW7OQcTwuM8KFcEZVZFo5Q7h k2H+EcpdAEJcOLwXmpsnl6nmpw8oarV9LwXmA/kWSS7CVCc5nZg5AQdOcm570M4adu 5xb6XtF6o5tE0ZefzcOEq28Jl/WGMeMtIECSXfB5QXfOSxINzELlxWV5eg/zv/kGn/ Ck0YFiOTzYW0DW9cm178F5Nj3wHKBR+wCZc/wjAv+VYgxIwve3NmKG93XPr3n/eu4a d7l3c+h0l3xoCpklUvSNPIhysBPyuejuNd1rpBtclSZ6rWX+7HO0dKg70Hv/2xODsj copTtxkj9nZQw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e4G-3UKF; Sat, 21 Jun 2025 21:55:58 +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 v2 11/15] scripts: sphinx-pre-install: fix release detection for Fedora Date: Sat, 21 Jun 2025 21:55:50 +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 48AFC270ECF; Sat, 21 Jun 2025 19:56:01 +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=1750535761; cv=none; b=aVXagkPlMz4ih6My4lMahW6gmMcKb/eezK47U5eIHSLGaQ5jV+ZKkZBhpMbNE3NqIOYD0nqwNtRWntdtTUguUy40QF+IGVq6RgIBVo1DZ27Qo2nv27gINmwTdOmpj0/wBaaNEdsqYBKjqEmMlemlDMqESWBW4rxtmkBHgh+mzPk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=y8LZ0fXrmuwyAMvRo91pI8wsN2CZiBu2VRksVUBmRVg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=s/RwP9ShywsyRDX7TdPTy7u7+QqSKrw/FUb6nwGNTXMwqOv6lIUNk1FvhouZS+NiUj7V+nXh0XoZD213vRCXR+04aODZkTQSkKSMcREw7tpI0hVoud01SwPHqeYric2G3is/s6bgZYjHN15dXTeBMLViSn7p3Vwh3NqD9yq7IX0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=kLqUlr1n; 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="kLqUlr1n" Received: by smtp.kernel.org (Postfix) with ESMTPSA id AEB92C4CEF7; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535760; bh=y8LZ0fXrmuwyAMvRo91pI8wsN2CZiBu2VRksVUBmRVg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=kLqUlr1n+TfBEGpK4FBNaNDec7oYi3DJOT/Ci9PnXtyvKNJKtZQ6dPdM9toVihJWF h6MjWsRNQJWJSPzItbaZhhqKEVmiSFP07FcNMxsgmZUWxy7u0RVoUZWovCiwgvaSTr qQYL7Y0i6kFISQ80CI4sU3C4gFcdOl6FqLUzuMnpTd1fxOBCIki5a+r/+i8LJgKFma emCV8JI8R3lRlbO1K9vawhW6ROHSk2Snej2JjAGK/Ejk2bgiNJsROwCUgFHTXlfumk GFyySLO1nNQtG/gvU0OzvkJC9brw15trnPvIqOSXBvgOVA3N+tMD28uxp/P1ULKLCR vd4O8S7MPlXpA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e4K-3bGK; Sat, 21 Jun 2025 21:55:58 +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 v2 12/15] scripts: test_doc_build.py: regroup and rename arguments Date: Sat, 21 Jun 2025 21:55:51 +0200 Message-ID: <0a9b4666029d7ceea73a4f922043bc334bb62d9a.1750535171.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" 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 41EF2270EBF; Sat, 21 Jun 2025 19:56:01 +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=1750535761; cv=none; b=V5RVYktysQ0hv+bNChqpMVl9BMJg9EdTFWatbQSY474gfbWJ2f9H9lP5fkVO2NepDrqLXCeylTNyR5s8PMdpEO4gbPyrtAwg+wrMn6Ppad7Y2QmC+iHcQEneH3ve/jXpw94zLFE/JIxCkINwrdkmp5lhsyEFkCkpuR6KjBbr+UM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=3yI0hd++pTAVk6UlNj1uaAE4va43OAIfWkR3JnQPolk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=W4RGvrZHhrh0gx6XOpM91DW/8bNcSAOAvmoGHUgiHjLvd20vBRxCh/Jjec2kWGYaDJJUqFplNfo5vsf8JYpwzEgJHtkqoyO0+QTFS74Pq9ZSFz7orPHmShWQbmRk4FI680cgDpro178CCcqsdkOENSMnURjjsKLNsT+/JlKQ3fs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=hBGPoQ6I; 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="hBGPoQ6I" Received: by smtp.kernel.org (Postfix) with ESMTPSA id AF44DC4AF0E; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535760; bh=3yI0hd++pTAVk6UlNj1uaAE4va43OAIfWkR3JnQPolk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=hBGPoQ6I5ihvFzE3BhClvLrR5MeGUfP3lE+/jI6+EoJgc2UJjsWi5OgY7YY5UenuJ C9q8kL2ROLsMzi2MqK2fJwyN+ZxAeHmjjEItV4CPhrZnIBMZa2/UnZkj+8okOSP5D8 u8+YwfyyEC1i+NZQwY1Zff4WZopx+NzbmdEKRZIQR7oD+BokXvOgk6dIwkoC3MB/Q8 GiGTE+3l4csDVvqmnpJWkYYv4HzZZPeIfHDVZvT4jhFXrcrV+tveTuCtdAGGPilyds cX8Vwxx6Ftyxl7peaDYNG6JssTJKb+WgGTxyNK1T9RnysaPW3x4x4aqv2VfDQIeoNd LKZUgvrAzr21g== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e4O-3hyM; Sat, 21 Jun 2025 21:55:58 +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 v2 13/15] docs: sphinx: add a file with the requirements for lowest version Date: Sat, 21 Jun 2025 21:55:52 +0200 Message-ID: <3bfcb9d4ddb303e2f0dd678fc590bac52bb4c1dc.1750535171.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" 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 79077271444; Sat, 21 Jun 2025 19:56:01 +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=1750535761; cv=none; b=t4VjhCI2mKvqi6RtV0CPJ6N45VLIF7NrIbQr7nDqL+2DRUiEEY8Yiq+5nwNsJGv+flSdI0Uk117nZCA+c+ZBfyFI0vllvcXhhI0tsLG4nNBWacp+RKOQmNb1exOsgs6zVEhqPHFo8OSeu7Qw36RlyDV/jwPMGJswKX0PvR6ANXk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=DJWn2NdXSfYMasLzdx/Yi+SRy9LroDQ3ca9CsyiDFIY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=p9EzdDq7+Ng/eZpT+AZUebk9VasFujhuOsJc8wFl9AA0M5apxlNsQkgBBNPQ7Cowr8wylrLB1a5OJSKyCQk4ag5Cd5RFRfRA6oxs4Twg2jlhI76rJgTt8VDNMB0EGkE9mUIllrFEmfu2S+rzGyjWXHEVnjXD1CB4tX+v77QWcXE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=jxXFEcru; 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="jxXFEcru" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B6E7CC4AF0F; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535761; bh=DJWn2NdXSfYMasLzdx/Yi+SRy9LroDQ3ca9CsyiDFIY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jxXFEcrugy1YL8nO4LprIAPvIGOTHSsE4W8YhBNZNBFdAqHcnlzV/KwTNleFa2R62 soRWcHtyqG+Psy/L9r8EVnS0VUz/lArjD9wCcM4L71XehQYBSn8r2bLke6qpQS4Q4I OJpisPFUAk+UK6ZGZqAP1P4VsYbpXpTHTyK8jw3ao7JDzMkMf3HqB9+1hrXwuZNa0s fk73T1XxAQ80RCvXWNIP+LjBnyJOC0t43P9tb2w3qrPjBSuvcnHwZFxEKVVLxo6srm i34Kb+gx6/By/QB0jBkdrdY/uCVxGAFYAurV2nW8NUNUuuAZx2tBpsByXfLBnUihZz +owtG1foQ2SyQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e4S-3pCG; Sat, 21 Jun 2025 21:55:58 +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 v2 14/15] docs: conf.py: several coding style fixes Date: Sat, 21 Jun 2025 21:55:53 +0200 Message-ID: <9b642e7063eff6a1d1a6a24bddcabee1fab97a2a.1750535171.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 | 354 +++++++++++++++++++++--------------------- 1 file changed, 174 insertions(+), 180 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 4ba4ee45e599..e4dde5aa4559 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,23 @@ 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): - """ On Sphinx, all directories are relative to what it is passed as SOURCEDIR parameter for sphinx-build. Due to that, all patterns @@ -53,15 +57,12 @@ def update_patterns(app): 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 +72,17 @@ def update_patterns(app): 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 app.config.exclude_patterns.append(rel_path) =20 + # helper # ------ =20 + def have_command(cmd): """Search ``cmd`` in the ``PATH`` environment. =20 @@ -88,24 +91,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 +182,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 +211,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 +234,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 +321,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 +367,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 +382,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 +463,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 +504,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 +516,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 +535,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 +549,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 +564,8 @@ kerneldoc_srctree =3D '..' # ------------------------------------------------------------------------= ------ loadConfig(globals()) =20 + def setup(app): - app.connect('builder-inited', update_patterns) + """Patterns need to be updated at init time on older Sphinx versions""" + + app.connect("builder-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 45795270EC3; Sat, 21 Jun 2025 19:56:01 +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=1750535761; cv=none; b=U8m94qyhKF3670dxsU8/BBMWKu99uP+1xHOSXLkd8HHKxb9cCPICUAkhzIKdKsJ3IZWWT3TqXEy3HA1Iu5KadDqMFhgIyQ2yyO6kiPaVOqsxDulVB0RlHdgdKC2Wf6ePlO0rktBJido2CtPn3x27r5C6Ue1ihfMXngPdP1FrdfY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750535761; c=relaxed/simple; bh=khxESugvHoab7laZWP+H+C5kr4pyhiqASuyv6rTuJKE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=S10zGW/sOlRYKb2Ei1n0xuIXAh86WeYfyMB+xC/ejGCsRhMgzykT1T7LFUiGz1b36slcdEnJ3B0VdBFAi0TueyPva9bZ1R+k+mogEk33iknCkgKk5H2Oym0p9fsQYfSFlQM5uPMtX3XJKY7OGTcqYigBxPA322Z/DTMxLriOqoY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=dp1psRkU; 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="dp1psRkU" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B3D0DC4CEF6; Sat, 21 Jun 2025 19:56:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750535760; bh=khxESugvHoab7laZWP+H+C5kr4pyhiqASuyv6rTuJKE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=dp1psRkUmVcMiQ8ujWmHoEzo5n2XUKxwL/FYx3VN94UmuKi0gKMX7VD2KQOAWjnlS GlQXF7Aw3NzLr0OIMOk1GKqGhx4OL29Oww5mbiHVl2OGPsmCGjQza5Br2HQp0EiMgJ LqhGSuh8H2SklXq0jqKmptVSmjD8GNIutM47NBryZ3mu+0myk9oVsUha5rveYVJCMN U1JdfemInq3t11K4Uo6Bc1DHYNovu9mlKsG+hFU2m3k/GVzKmByJqE84B+asy14Os3 MenOjloVq/dNnHsVFuY5+lBnzM5ouSGxTsZJvizCgQPCNjfS7y4LPBBMSRRCi1byuK eNvxrnXvkV3Dg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uT4Ji-00000000e4W-3w9n; Sat, 21 Jun 2025 21:55:58 +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 v2 15/15] docs: conf.py: Check Sphinx and docutils version Date: Sat, 21 Jun 2025 21:55:54 +0200 Message-ID: <52e195e9660e2086bc90da977e7d4e8b9efe53f5.1750535171.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 e4dde5aa4559..945198bd1f1f 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