From nobody Sat Feb 7 20:57:56 2026 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 6A22A1A3172; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=ETUkyUCrE/7wF/7Q4Ovih8BFv9/DPyYH9m841VkiSe/sW4mVEmHNmsE6tMW0yF3e2/0kt7OkCQZM3sUlwHLYXIZshgG6G7CnmmfwHnF/5fJsIEL6tVvlQVEV4twb8erCE7TJG+Ols+zK1OUxhxoV5tley7lDTM85QetVV/GRhD8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=TKR+6Sf3vzBuaU+H9wxtOvYytkyV04qz1b4yGIhER0o=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=NXiFY5fL/fNOy7boLdAicPZ7fCHMRFOIuNLpkPLrZZHRX7KSsWwOIio8xrhTnSMzktpUhqg6edFHCR2/8/KnObcJAZTrpIA65nPTJKeYghJyZvN5dGA+dpIh0jvXjQZLQd9K2fCnaZJHSPEQ9k+Qg7InfPXhKKqi/xi4En4qu3M= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=sKml/KHO; 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="sKml/KHO" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 24232C2BC87; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=TKR+6Sf3vzBuaU+H9wxtOvYytkyV04qz1b4yGIhER0o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sKml/KHO/fdbULomu2DUJRk8Ii199it/B86L1dXvs/OsYeFms7ZIPWeWZRTD/69Hd EQNkkb+TJlnXpNtKDktlpDyKN8Z5+pQbkegGonq3mOw0sN0nidEjCnS0RXQwbKfVji 0l7UMuHU2sv5aIKXwbrMeY/wzhyQP8oQ5j67vzFF9/5t+DjI/OK2bmZOURtl3t4rBS 8B+6rc5di+vJFNE3313/IJOUkeYmIqcxsgaDSJrQgtxGQ57QLpzDUyBTLeG8Tt56tP D9Ka7XoFfAsdHEAQDs6VFNzZq3wUi8BvO1MBeqlhy8Q84tZWNOvN9lZ54OUQuKuT1Y NFx4pLHYtuEjg== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j1Q-0T3M; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, =?UTF-8?q?N=C3=ADcolas=20F=2E=20R=2E=20A=2E=20Prado?= , Mauro Carvalho Chehab , Petr Vorel , Shuah Khan Subject: [PATCH 01/25] docs: custom.css: prevent li marker to override text Date: Mon, 19 Jan 2026 17:23:04 +0100 Message-ID: <4f28c485b72ea27c0981cd950a1819597d6736b1.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 There's currently an issue with li marker: it is set to use -1em, which actually makes it override the text. This is visible on indexes that are deep enough. Fix it. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx-static/custom.css | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-= static/custom.css index e7ddf3eae7ed..6757b5a59f23 100644 --- a/Documentation/sphinx-static/custom.css +++ b/Documentation/sphinx-static/custom.css @@ -30,6 +30,9 @@ img.logo { margin-bottom: 20px; } =20 +/* The default is to use -1em, wich makes it override text */ +li { text-indent: 0em; } + /* * Parameters for the display of function prototypes and such included * from C source files. --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 6A2C1278753; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=KW1lmBgf6X60rZSqXS/+y2S4kG93hGbJyIYZdykIvFUnu1339+V6UZRmdlh0zEHWCBbYSeZr0AwGnjqyNUnV39mGQaZVrI8RNFxYW1nhRBxAZjdmhN+kwzt/AHMcphdBQ1saKkEDnroQUxTw5IkjZc3NgRLVIeYF3mMR88Th/Zw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=q9VxELkw10h/rayaXE5+jzYIauBY7bQAjcvZ82AeO5k=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=GJimQdfHm+RcqOihXCGzOtWp1YK+Aeh3yZmzpdZkNEyv1YOHMF1VnUNobtnum8oE6pQplvcOExv7SOnhGAuNWN8xkrRMGjQDNN6Mhyt15Mg5D8J5ei67l507s/b4RLjaoEqo/YoZRtX2uJjyCpvnHbNMKLbq6nidXPCkFzcFV0c= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=jTN9MNJH; 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="jTN9MNJH" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1ABA9C19424; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=q9VxELkw10h/rayaXE5+jzYIauBY7bQAjcvZ82AeO5k=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jTN9MNJHKq7WPD8YIdnuGw36G+6WOcbFAc+GtI/JhosWzODPfVU6qtfsS/oQ333Jx PyCGrVVYU9SNKL8LWbgalCTZRh0wlveViokXxunoO8hjo5VFZYSRvczZJi4ywB2EzP Cg06e5LZ8dWDJAqUYp1f8Ukvx0G5qCZ8Tmko47cKNRmn/52AS37mbuhXcpYa9PKbam Qj1DiR5PxDIs9ip7SH/y0FXbVPaUrqA831Nj0HL/D28Huw+toS2/8kAnqS+9q43NeG /WUQmzEkFLINPT+yzxbG1lj1MGOr8gGF2Q4zVY9tClXGvMF+7s+DPbsg/QJhS+qk/z jTw32JR6d3ufg== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j1U-0Zzq; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan , Jani Nikula Subject: [PATCH 02/25] docs: conf.py: don't use doctree with a different meaning Date: Mon, 19 Jan 2026 17:23:05 +0100 Message-ID: X-Mailer: git-send-email 2.52.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 At Sphinx, doctree is a directory where doc build cache is stored. Use a better name. No functional changes. Suggested-by: Jani Nikula Signed-off-by: Mauro Carvalho Chehab --- Documentation/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 16d025af1f30..10322b1a28a7 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -33,7 +33,7 @@ else: include_patterns =3D ["**.rst"] =20 # Location of Documentation/ directory -doctree =3D os.path.abspath(".") +kern_doc_dir =3D os.path.abspath(".") =20 # Exclude of patterns that don't contain directory names, in glob format. exclude_patterns =3D [] @@ -73,7 +73,7 @@ def config_init(app, config): # setup include_patterns dynamically if has_include_patterns: for p in dyn_include_patterns: - full =3D os.path.join(doctree, p) + full =3D os.path.join(kern_doc_dir, p) =20 rel_path =3D os.path.relpath(full, start=3Dapp.srcdir) if rel_path.startswith("../"): @@ -83,7 +83,7 @@ def config_init(app, config): =20 # setup exclude_patterns dynamically for p in dyn_exclude_patterns: - full =3D os.path.join(doctree, p) + full =3D os.path.join(kern_doc_dir, p) =20 rel_path =3D os.path.relpath(full, start=3Dapp.srcdir) if rel_path.startswith("../"): @@ -95,7 +95,7 @@ def config_init(app, config): # of the app.srcdir. Add them here =20 # Handle the case where SPHINXDIRS is used - if not os.path.samefile(doctree, app.srcdir): + if not os.path.samefile(kern_doc_dir, app.srcdir): # Add a tag to mark that the build is actually a subproject tags.add("subproject") =20 --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 98B872ECD1B; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=tJ6b5R+D0RtsKoMd5HuEzP9nDCQ4P5/bo8FZqp5Uhrr3kcllrLyduiwecvMfg8LcbU7661VKQ2PvTHXRjM6UrcOMURVwMaGdzkMhH8KTZLhfNPcMDwTUjPgw1QPUoCtfKS79GrftpupQAkNtRwDwL+5bSDFexaMKSpxNnYfpVbo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=tNwPLQqH9SM9VjmePHUTFyoY/BU3+KBoEbLstSF4Kg8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=dEHauqV+v0zT6N0VJuPmO5t+ZBsQkthRaPP2O2B78UOAB4ZaOyim3n51Wdp57DTUKKhcSNwFzZeU+ELFqDYGlv4DkAwiKpXmMUzzK7Rga1i0KRUNJMyLdRE4b9SAnukXX+5F3i1Dg4RDDJ5A3gdgN9AFziNgzdvrxc0NR0Gpi2w= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=UKnmkQ+T; 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="UKnmkQ+T" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 30A22C2BCB3; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=tNwPLQqH9SM9VjmePHUTFyoY/BU3+KBoEbLstSF4Kg8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=UKnmkQ+Txf9E4pMu9SH7MCRYL0OUcVgnrZLC4oacf5LzLsn++og1QgUBsi2f0wmV0 DWZiINaVqzTMSqwtVJjb+Uxmg11rz+TKyzAUzDA+qyemlNBSZpiby4uW8yIzFkUoOt egwTnfKAIvMjB2McW0zFH/8KLBVuE5mqGy5YGw27XAn5AY2zLMWq8YGechxfw9F8wu h92W2wqO0Q/YX2RYqi7CX3L1TSooR7ePVwaxohx96LLqdRRRdagrx8mjMxTBxGZ9bY /NRHrOyS+nOf2+u2GztDObBi9x5SuByIQSIFYu+1o0GPLl3QZLMyItHlFXpHmwsJgM VftZgcLQxaOGw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j1Y-0h1Q; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan , Jani Nikula Subject: [PATCH 03/25] docs: conf: don't rely on cwd to get documentation location Date: Mon, 19 Jan 2026 17:23:06 +0100 Message-ID: <34c38718dfade91ff6f7afca5e9c1705ba253c97.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 Instead of relying that Sphinx will be called from Documentation/ dir, pick the location based on __file__. Suggested-by: Jani Nikula Signed-off-by: Mauro Carvalho Chehab --- Documentation/conf.py | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 10322b1a28a7..f0367c48adc6 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -13,10 +13,11 @@ from textwrap import dedent =20 import sphinx =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")) +# Location of Documentation/ directory +kern_doc_dir =3D os.path.dirname(os.path.abspath(__file__)) + +# Add location of Sphinx extensions +sys.path.insert(0, os.path.join(kern_doc_dir, "sphinx")) =20 # Minimal supported version needs_sphinx =3D "3.4.3" @@ -32,9 +33,6 @@ else: # Include patterns that don't contain directory names, in glob format include_patterns =3D ["**.rst"] =20 -# Location of Documentation/ directory -kern_doc_dir =3D os.path.abspath(".") - # Exclude of patterns that don't contain directory names, in glob format. exclude_patterns =3D [] =20 --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 9AB202ED87C; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=pu5YAayD5oynjHK0QZRfjoS9Cz5QRTF+Z7fGtjE4LCsJoHycmZ9DKNCmNGQQjWumwbBxK0zefX+U6IdMWVoVJGl7D6spvxm64//W6nu2lg2EiQV7DcGXaSnFicbS6c/U2yRFFB9Wc17NrvwQRa7/Ov7/41njUHDwvkYlwzHc3FA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=mPoXsykZwoJHu81axukvCM9Wxj8onSTSnhXLGIOaGNw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=F/u7A4XgA26PWYhE65bRmUz9QSxNf4VC79xh3YvPhfUoydamwrBuhlvlQZ72U9IRJmn2r/I4sJ4XYOywCCl1YpFb1GmbBzojgi5lnJzv2S6k7CIEgiq7YfpE/3jHlFe9AhKarhe5apzp3K95ZYLvLmMtwnMaWHHPjOCAAiALR1k= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=MjFUlCI1; 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="MjFUlCI1" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 34571C2BCB4; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=mPoXsykZwoJHu81axukvCM9Wxj8onSTSnhXLGIOaGNw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=MjFUlCI1Mw5pv+EGdE0j/yKQRUz0sO+yCxNt64Au8vRv/dd8vnGj9reI/DXoTNxXM djlzO1jTt8XhmZi2OiHK3SI6oKCAiTmjRYFYMKOf/F1zjw3bKFLmZLJLcPil7mTTbw OYYOvS6eblNTS5xKIGEHRodhNUh79xmW6jnwtz5BscN5fAtY26XZRrWvv3UMQU3PvF Fk9MagOsRuy2or/gcXOO8N8NpL5bQ0vADAlIuoITs+pLkDyqIEI4PTEShV4YBEmXh5 MEXXhPN58zQRjoEq0mbehJlHfqaRsFtdzGaM1y1zfuXGGtqqr+osqJU3YgR7O4qha9 zlq52Urr1s9yQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j1c-0nsu; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan Subject: [PATCH 04/25] docs: enable Sphinx autodoc extension to allow documenting python Date: Mon, 19 Jan 2026 17:23:07 +0100 Message-ID: <29cbe375dc418d6fa5793f55199799b5b52dcd38.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 Adding python documentation is simple with Sphinx: all we need is to include the ext.autodoc extension and add the directories where the Python code sits at the sys.path. Signed-off-by: Mauro Carvalho Chehab --- Documentation/conf.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Documentation/conf.py b/Documentation/conf.py index f0367c48adc6..8e786fe6007f 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -19,6 +19,10 @@ kern_doc_dir =3D os.path.dirname(os.path.abspath(__file_= _)) # Add location of Sphinx extensions sys.path.insert(0, os.path.join(kern_doc_dir, "sphinx")) =20 +# Allow sphinx.ext.autodoc to document files at tools and scripts +sys.path.append(os.path.join(kern_doc_dir, "..", "tools")) +sys.path.append(os.path.join(kern_doc_dir, "..", "scripts")) + # Minimal supported version needs_sphinx =3D "3.4.3" =20 @@ -152,6 +156,7 @@ extensions =3D [ "maintainers_include", "parser_yaml", "rstFlatTable", + "sphinx.ext.autodoc", "sphinx.ext.autosectionlabel", "sphinx.ext.ifconfig", "translations", --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 6A32329AAEA; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=PQiDn8KH3UV3YspXTnz+RJ/lVUhmlzwnyW1NtfddAP8kBJ3xkd4WsKHx//839BQ/1z0Afw0TRDBnAkKfi3RIFfu9qmfni7ma9gRALHQEKiY/AWeaKp6jLNu0zRKnZN+Z5Zkm/yycdEHLSjB8Y8+woKJ5zrbm2UQ9NSIvX+P17P8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=F1iY5tojuZW+LSnzsdjV0WpgMur3Wq5H16GM35OkDAw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=XrsHeTjliwZjTVjAD/aij2CFH5UDZPO5rG58OgisBdw0B1WonjJfPYI9VISO/G3nMTLtLsRY3FwX88q7ia1kBwz3plFvdt25786gJfJO5fTt8LBz+krsF+GgrT+3URiY64d5AQDUOmSfjGxMIU7LU9WqzotMX4uNR7lHFQH7wKI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=RKYLUVTp; 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="RKYLUVTp" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2008AC2BC86; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=F1iY5tojuZW+LSnzsdjV0WpgMur3Wq5H16GM35OkDAw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RKYLUVTpsDNrjnX6F8SLT7Cj9fyQQcqw/2LyzDlBedMwVf4N7dsQLBUGUenFGaoO2 H9CleZU7ccLfFoznE4yCQIylN3HMWYucKkf6E2GlAKDr17jYp5NYulkIAFgu5Q5lAk 4Q1J8T2yc+Nqw6R/VWrkuUJs9K9nl+M5Kohw5MSdexQBAQBMslCQE1XQuAF4IyQN4Q wWD+cQw5Tgm8LSvJzGcUQ5twdLKed8a5h7KsZOSqxfPxU4DaT7dQi2ThmnDz5Wq2gM NbAf5jJACFGQjJmTxoJvcH8JQxRQBdqfA5CXj9ByoJ1/t96LZdhlngPGzywNlvUEgr SsbVv0bf13djg== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j1g-0uiw; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, =?UTF-8?q?N=C3=ADcolas=20F=2E=20R=2E=20A=2E=20Prado?= , Mauro Carvalho Chehab , Petr Vorel , Shuah Khan Subject: [PATCH 05/25] docs: custom.css: add CSS for python Date: Mon, 19 Jan 2026 17:23:08 +0100 Message-ID: X-Mailer: git-send-email 2.52.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 As we'll start adding python to documentation, add some CSS templates to better display python code. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx-static/custom.css | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-= static/custom.css index 6757b5a59f23..db24f4344e6c 100644 --- a/Documentation/sphinx-static/custom.css +++ b/Documentation/sphinx-static/custom.css @@ -43,6 +43,15 @@ dl.function dt { margin-left: 10em; text-indent: -10em; } dt.sig-object { font-size: larger; } div.kernelindent { margin-left: 2em; margin-right: 4em; } =20 +/* + * Parameters for the display of function prototypes and such included + * from Python source files. + */ +dl.py { margin-top: 2em; background-color: #ecf0f3; } +dl.py.class { margin-left: 2em; text-indent: -2em; padding-left: 2em; } +dl.py.method, dl.py.attribute { margin-left: 2em; text-indent: -2em; } +dl.py li, pre { text-indent: 0em; padding-left: 0 !important; } + /* * Tweaks for our local TOC */ --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 98A6E2EB85E; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=oZar4wOy/zBxljMxJzoBIeXIzmm1Ev2PTHBeaHCc1Y5dumEForLgCghNZAm10aQgczcrLFOlS5RzLQVKZ8WavM72RhjK6q5/mHUHZZrCrr69JJhz93VxXL+cqW9kqiIjK+K2H2uOxqYIcfzTczqmq4iFf3mKGmDihT7oICvTI0c= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=V/BLZs4Nlt58GEgPnSOwtNktnB67g/V/fdysHWNMdM0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=NMY2O/QqoJUijH2o6u0076UGFgwnho9mFgt+XONGh4jnmblhmQoHAMqmDTCEqQweuOc/DLSBapf82wlh0+Q62dXm34lsYckKpEumYGa7zBi/Ta21WKAyMjKTIbctrI/PJPkaSlXnnf5crYP+K13Qfs6zkvlO0C8xl+pwbbxjfWY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=U2gjrXwL; 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="U2gjrXwL" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 28CCDC2BC9E; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=V/BLZs4Nlt58GEgPnSOwtNktnB67g/V/fdysHWNMdM0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=U2gjrXwL1OlFQWyjT+UgU+lYWTdcwwRnJSHkiDHLdmw6bXAZXU4IUvMr0on4LBQsx gmSji4zZuwDKJPBc20MHmzOnEI2NCKqyXhAbwTKuh03AbtWrecncHwLrWZvshjF+Pp aoKZlTSLZlBgFVEawqikk06RxXoblqe1h7uS/qtl47N3i5BP8QjPTrTcO5gqk/Ehr6 yONByuxhWpSpSbSHiUlVNt6VWdXx6T2UyRGHBo+os1q1J30F8kjfvBdiXCswJAwzCn rkh3DlrtYFPrFX9fz02QerjF0lHMJZyQdnHb6aTEexYGMbvCEpMLaa6DXgpQpRuhb4 +pOv7xBTTDTaA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j1k-11Yz; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 06/25] docs: kdoc: latex_fonts: Improve docstrings and comments Date: Mon, 19 Jan 2026 17:23:09 +0100 Message-ID: <6e0eb2e245eae9b4f39cf231dee32df00b9e8b7b.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 In preparation to document kernel-doc module, improve its documentation. Among the changes, it had to place the xml template inside a code block, as otherwise doc build would break. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/latex_fonts.py | 95 ++++++++++++++++------------ 1 file changed, 56 insertions(+), 39 deletions(-) diff --git a/tools/lib/python/kdoc/latex_fonts.py b/tools/lib/python/kdoc/l= atex_fonts.py index 29317f8006ea..1d04cbda169f 100755 --- a/tools/lib/python/kdoc/latex_fonts.py +++ b/tools/lib/python/kdoc/latex_fonts.py @@ -5,12 +5,13 @@ # Ported to Python by (c) Mauro Carvalho Chehab, 2025 =20 """ -Detect problematic Noto CJK variable fonts. +Detect problematic Noto CJK variable fonts +=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=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -For "make pdfdocs", reports of build errors of translations.pdf started -arriving early 2024 [1, 2]. It turned out that Fedora and openSUSE -tumbleweed have started deploying variable-font [3] format of "Noto CJK" -fonts [4, 5]. For PDF, a LaTeX package named xeCJK is used for CJK +For ``make pdfdocs``, reports of build errors of translations.pdf started +arriving early 2024 [1]_ [2]_. It turned out that Fedora and openSUSE +tumbleweed have started deploying variable-font [3]_ format of "Noto CJK" +fonts [4]_ [5]_. For PDF, a LaTeX package named xeCJK is used for CJK (Chinese, Japanese, Korean) pages. xeCJK requires XeLaTeX/XeTeX, which does not (and likely never will) understand variable fonts for historical reasons. @@ -25,68 +26,77 @@ This script is invoked from the error path of "make pdf= docs" and emits suggestions if variable-font files of "Noto CJK" fonts are in the list of fonts accessible from XeTeX. =20 -References: -[1]: https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/ -[2]: https://lore.kernel.org/r/1708585803.600323099@f111.i.mail.ru/ -[3]: https://en.wikipedia.org/wiki/Variable_font -[4]: https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts -[5]: https://build.opensuse.org/request/show/1157217 +.. [1] https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/ +.. [2] https://lore.kernel.org/r/1708585803.600323099@f111.i.mail.ru/ +.. [3] https://en.wikipedia.org/wiki/Variable_font +.. [4] https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts +.. [5] https://build.opensuse.org/request/show/1157217 =20 -#=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=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=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D Workarounds for building translations.pdf -#=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=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=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D +----------------------------------------- =20 * Denylist "variable font" Noto CJK fonts. + - Create $HOME/deny-vf/fontconfig/fonts.conf from template below, with tweaks if necessary. Remove leading "". + - Path of fontconfig/fonts.conf can be overridden by setting an env variable FONTS_CONF_DENY_VF. =20 - * Template: ------------------------------------------------------------------ - - - - - - - - /usr/share/fonts/google-noto-*-cjk-vf-fonts - - /usr/share/fonts/truetype/Noto*CJK*-VF.otf - - - ------------------------------------------------------------------ + * Template:: + + + + + + + + + /usr/share/fonts/google-noto-*-cjk-vf-fonts + + /usr/share/fonts/truetype/Noto*CJK*-VF.otf + + + =20 The denylisting is activated for "make pdfdocs". =20 * For skipping CJK pages in PDF + - Uninstall texlive-xecjk. Denylisting is not needed in this case. =20 * For printing CJK pages in PDF + - Need non-variable "Noto CJK" fonts. + * Fedora + - google-noto-sans-cjk-fonts - google-noto-serif-cjk-fonts + * openSUSE tumbleweed + - Non-variable "Noto CJK" fonts are not available as distro packages as of April, 2024. Fetch a set of font files from upstream Noto CJK Font released at: + https://github.com/notofonts/noto-cjk/tree/main/Sans#super-otc + and at: + https://github.com/notofonts/noto-cjk/tree/main/Serif#super-otc - , then uncompress and deploy them. + + then uncompress and deploy them. - Remember to update fontconfig cache by running fc-cache. =20 -!!! Caution !!! +.. caution:: Uninstalling "variable font" packages can be dangerous. They might be depended upon by other packages important for your work. Denylisting should be less invasive, as it is effective only while @@ -115,10 +125,15 @@ class LatexFontChecker: self.re_cjk =3D re.compile(r"([^:]+):\s*Noto\s+(Sans|Sans Mono|Ser= if) CJK") =20 def description(self): + """ + Returns module description. + """ return __doc__ =20 def get_noto_cjk_vf_fonts(self): - """Get Noto CJK fonts""" + """ + Get Noto CJK fonts. + """ =20 cjk_fonts =3D set() cmd =3D ["fc-list", ":", "file", "family", "variable"] @@ -143,7 +158,9 @@ class LatexFontChecker: return sorted(cjk_fonts) =20 def check(self): - """Check for problems with CJK fonts""" + """ + Check for problems with CJK fonts. + """ =20 fonts =3D textwrap.indent("\n".join(self.get_noto_cjk_vf_fonts()),= " ") if not fonts: --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 98B012EC57F; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=jiBAc/3uzihMVPlSogn0JwE758hgmh+YcdtVNipCmdxOZCb5e2zPrt39ZJ2i3yxYPX0mvSb/xj+dKgHRmbQovAshbVENW87QQJykFJz1qj7ucpcfVHyS5OIyCyZ4XjNbsHu+NxdDcyp36j19NJoW7Q78nEHGtZ+pqA35+ud/lOs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=D20byBH6Dc3S8kqec0afWoBETHqoICKqefEL4fRTSCc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Th03JsIIg+IAaShS8/lsklbQeW/50pA1uegXzl9AKLN0SGxiGv7sdRWCaRV57YKUAXxA3siYfx51UrD7wAH23JZ2z3voMQad85Uv7ULiAc2sMnD74vhQXgkY8wtmSLK7h2X+dzqfl90vy73BEdh7IcoKh0UeRWIummZcpf14xc4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Jl9xTGhZ; 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="Jl9xTGhZ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 33919C2BCB1; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=D20byBH6Dc3S8kqec0afWoBETHqoICKqefEL4fRTSCc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Jl9xTGhZP81pMASVBixB9YAMFXfrS9/5eWyOyCuUnC8FLyrjeye65il4eYvkPBWC5 kNl3Y1X6t7EhxRJ7ReeuETRq5NLQYZkINiMTvzo2fFK8uIMeCX+6I7j2spzPRW2sKO +gjiZVMupze9b3FtxtOJyFnYZ5z0bN/801Q+1N1ZIMdkH5jVKmFrTzAalCv1ecpppU /Qg6e1Z2F+9W9vRXhpC1oFQOWkEi1XHcFlZwmxYhm6DW2CaBgIEyn8iKJI9cWyQRSh Otkf9Mb3E9BGFEFjv+PniDanHlgCvD+vIdcSzwimgI8H63QV/hDcIwwGlgsFtSE2s1 iRaCPEXPGhPiw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j1o-18QL; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH 07/25] docs: kdoc_files: Improve docstrings and comments Date: Mon, 19 Jan 2026 17:23:10 +0100 Message-ID: <75d58878ad6f83f24f1c0ce9e04301a000ecbaa3.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 In preparation to document kernel-doc module, improve its documentation. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_files.py | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kd= oc_files.py index bfe02baf1606..022487ea2cc6 100644 --- a/tools/lib/python/kdoc/kdoc_files.py +++ b/tools/lib/python/kdoc/kdoc_files.py @@ -5,7 +5,8 @@ # pylint: disable=3DR0903,R0913,R0914,R0917 =20 """ -Parse lernel-doc tags on multiple kernel source files. +Classes for navigating through the files that kernel-doc needs to handle +to generate documentation. """ =20 import argparse @@ -43,7 +44,7 @@ class GlobSourceFiles: self.srctree =3D srctree =20 def _parse_dir(self, dirname): - """Internal function to parse files recursively""" + """Internal function to parse files recursively.""" =20 with os.scandir(dirname) as obj: for entry in obj: @@ -65,7 +66,7 @@ class GlobSourceFiles: def parse_files(self, file_list, file_not_found_cb): """ Define an iterator to parse all source files from file_list, - handling directories if any + handling directories if any. """ =20 if not file_list: @@ -91,18 +92,18 @@ class KernelFiles(): =20 There are two type of parsers defined here: - self.parse_file(): parses both kernel-doc markups and - EXPORT_SYMBOL* macros; - - self.process_export_file(): parses only EXPORT_SYMBOL* macros. + ``EXPORT_SYMBOL*`` macros; + - self.process_export_file(): parses only ``EXPORT_SYMBOL*`` macro= s. """ =20 def warning(self, msg): - """Ancillary routine to output a warning and increment error count= """ + """Ancillary routine to output a warning and increment error count= .""" =20 self.config.log.warning(msg) self.errors +=3D 1 =20 def error(self, msg): - """Ancillary routine to output an error and increment error count"= "" + """Ancillary routine to output an error and increment error count.= """ =20 self.config.log.error(msg) self.errors +=3D 1 @@ -128,7 +129,7 @@ class KernelFiles(): =20 def process_export_file(self, fname): """ - Parses EXPORT_SYMBOL* macros from a single Kernel source file. + Parses ``EXPORT_SYMBOL*`` macros from a single Kernel source file. """ =20 # Prevent parsing the same file twice if results are cached @@ -157,7 +158,7 @@ class KernelFiles(): wcontents_before_sections=3DFalse, logger=3DNone): """ - Initialize startup variables and parse all files + Initialize startup variables and parse all files. """ =20 if not verbose: @@ -213,7 +214,7 @@ class KernelFiles(): =20 def parse(self, file_list, export_file=3DNone): """ - Parse all files + Parse all files. """ =20 glob =3D GlobSourceFiles(srctree=3Dself.config.src_tree) @@ -242,7 +243,7 @@ class KernelFiles(): filenames=3DNone, export_file=3DNone): """ Interacts over the kernel-doc results and output messages, - returning kernel-doc markups on each interaction + returning kernel-doc markups on each interaction. """ =20 self.out_style.set_config(self.config) --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 98C982ECEA3; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=OGBcoLFtIx1ImRKgEyLW//aX3bCg7+yx0cCUKRNcZIocvMK3WouV59OVzgNb1zjfUpW4Ozym4u3PvXvxAikHzruwGCPS3xbDnJasigT14sNcxok594FCR2DQqM1oUgEMHcRvUm0PY0KUbJv4/IhnKqboHvLDa5zEoxHWwfiKwdc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=kmk1GvA8qQBm6LrMB53lcAYigASy9DuUwFJjdBAuCYA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=chJjPFMSERseWflJOIOtvCF2M4fQtg9H7E2lDA/yjOoWfi6h90d+sesAA6eD816qKWlthRwtp9efEhmpMl8YXDnPd3iirWXGYdPoSSO3dDoY8GrhcHABWFCSjMcXa3EzuaTAzR64irZo7tI9djYCER7EaltyK394iKJaWAYBkZI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Jb6G/OZX; 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="Jb6G/OZX" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2B484C2BCB0; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=kmk1GvA8qQBm6LrMB53lcAYigASy9DuUwFJjdBAuCYA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Jb6G/OZXZze8yAiPxyYcIkskwEVQixCDEkPRC8v8/IVWyNejEHzu3LzqFBnNS+GIr uubYwLjG6taquIKhrbQrEQ/+B+PssWOQaV+SjRSPUi8XOMSAALE0pgwSHJIXJH9UJI xD3+CrUUwoOoMV/Sql6E8IDYKJjXL4HD/P1TW3EF+g6BpytaCyVh1NGDjJSfD6wac/ xWIksy8yRjMhzQ/8uNeqSBR1p4pSIRJ/W9d3CIsVBMxSwCRaxE+CmEduF34PocRp5x S43gBxsef6WIptJLAB3PPE3GzBDKdmDzYfrCUZcWlSTYsbH7e5Kx56GyIybU+isFb4 Jw3kAH3KL2xgA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j1s-1FF9; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 08/25] docs: kdoc_item: Improve docstrings and comments Date: Mon, 19 Jan 2026 17:23:11 +0100 Message-ID: <65a7c6bb318e7a8cbf5c115903d507568099151a.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 In preparation to document kernel-doc module, improve its documentation. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_item.py | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_item.py b/tools/lib/python/kdoc/kdo= c_item.py index 19805301cb2c..2b8a93f79716 100644 --- a/tools/lib/python/kdoc/kdoc_item.py +++ b/tools/lib/python/kdoc/kdoc_item.py @@ -4,7 +4,16 @@ # then pass into the output modules. # =20 +""" +Data class to store a kernel-doc Item. +""" + class KdocItem: + """ + A class that will, eventually, encapsulate all of the parsed data that= we + then pass into the output modules. + """ + def __init__(self, name, fname, type, start_line, **other_stuff): self.name =3D name self.fname =3D fname @@ -24,6 +33,9 @@ class KdocItem: self.other_stuff =3D other_stuff =20 def get(self, key, default =3D None): + """ + Get a value from optional keys. + """ return self.other_stuff.get(key, default) =20 def __getitem__(self, key): @@ -33,10 +45,16 @@ class KdocItem: # Tracking of section and parameter information. # def set_sections(self, sections, start_lines): + """ + Set sections and start lines. + """ self.sections =3D sections self.section_start_lines =3D start_lines =20 def set_params(self, names, descs, types, starts): + """ + Set parameter list: names, descriptions, types and start lines. + """ self.parameterlist =3D names self.parameterdescs =3D descs self.parametertypes =3D types --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 BC6652FD699; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=Z/sm3j/4BSChWbAiQPjgXM3GZhuBzticiko28O9u/rCPAU7xWxmrnzOMGzvMSwtqPcwilj5bnmjBT+bsVfiGonWzQEW5LUpEuQ/x+L3ZVcrpvUBOuUzdyTUOohoYMkXHwo6iLOQyzl8EN1i79m3MXy5+8BV6GMLKA5IBSTpMm1o= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=xzN+qnwUzc8uS+xH26py+FM48k+pV86aU/2bH+RENHY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=LrE3Al3HhEoTHY6T2rJkr0QS4bkI2fzU3wHQHzm0c6YfxdQcaDQhwPUoaO1KtwN1mi5aopsbaVWu9ERrmzutieLfN2k9bCzXvTKpdF5AWX2UBGLxsDVe+EhlZ2DiAeLtn/qwdsvwIns4Vi4pQHurl8ii3SAhRSciQ/dJFm4w0os= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=QzfpFgvk; 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="QzfpFgvk" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 21F14C19423; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=xzN+qnwUzc8uS+xH26py+FM48k+pV86aU/2bH+RENHY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=QzfpFgvkanSJQmRyZNC7OJAHR3jkdQBjDvAciwgzwAbF6XEmARWwrhxO1gm1kkUFK cArAJ4sgpnS1yc4ZqYl03rLMA+w0xsOzzibyKQ7X30l9NPc+W4iDPkDWe2w6HIhDjm F7ZlfApmvcoAisvsD8IwG5DMn/cExpN/K6ecE3/w1YztPQgjD/FSRqvNFUkP3awX+q S6EBJuch4pST8nOfMcxjtM/YRfqmWcSVf53XI0jrdO5cHDUXJiEuL0ijPSJnqixSIj 6CBWIJ7GY8s6lYzRfFXO+JiXIyUgLjZOZ5JKk8Le+WzP5DIc7YWzattbmeyKa99Ack keG9ptimh5RDQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j1w-1MBJ; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 09/25] docs: kdoc_parser: Improve docstrings and comments Date: Mon, 19 Jan 2026 17:23:12 +0100 Message-ID: X-Mailer: git-send-email 2.52.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 In preparation to document kernel-doc module, improve its documentation. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_parser.py | 169 +++++++++++++++------------ 1 file changed, 92 insertions(+), 77 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index a9a37519145d..bd88a2cd60c3 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -5,11 +5,8 @@ # pylint: disable=3DC0301,C0302,R0904,R0912,R0913,R0914,R0915,R0917,R1702 =20 """ -kdoc_parser -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -Read a C language source or header FILE and extract embedded -documentation comments +Classes and functions related to reading a C language source or header FILE +and extract embedded documentation comments from it. """ =20 import sys @@ -195,25 +192,28 @@ function_xforms =3D [ ] =20 # -# Apply a set of transforms to a block of text. +# Ancillary functions # + def apply_transforms(xforms, text): + """ + Apply a set of transforms to a block of text. + """ for search, subst in xforms: text =3D search.sub(subst, text) return text =20 -# -# A little helper to get rid of excess white space -# multi_space =3D KernRe(r'\s\s+') def trim_whitespace(s): + """ + A little helper to get rid of excess white space. + """ return multi_space.sub(' ', s.strip()) =20 -# -# Remove struct/enum members that have been marked "private". -# def trim_private_members(text): - # + """ + Remove ``struct``/``enum`` members that have been marked "private". + """ # First look for a "public:" block that ends a private region, then # handle the "private until the end" case. # @@ -226,20 +226,21 @@ def trim_private_members(text): =20 class state: """ - State machine enums + States used by the parser's state machine. """ =20 # Parser states - NORMAL =3D 0 # normal code - NAME =3D 1 # looking for function name - DECLARATION =3D 2 # We have seen a declaration which might no= t be done - BODY =3D 3 # the body of the comment - SPECIAL_SECTION =3D 4 # doc section ending with a blank line - PROTO =3D 5 # scanning prototype - DOCBLOCK =3D 6 # documentation block - INLINE_NAME =3D 7 # gathering doc outside main block - INLINE_TEXT =3D 8 # reading the body of inline docs + NORMAL =3D 0 #: Normal code. + NAME =3D 1 #: Looking for function name. + DECLARATION =3D 2 #: We have seen a declaration which might n= ot be done. + BODY =3D 3 #: The body of the comment. + SPECIAL_SECTION =3D 4 #: Doc section ending with a blank line. + PROTO =3D 5 #: Scanning prototype. + DOCBLOCK =3D 6 #: Documentation block. + INLINE_NAME =3D 7 #: Gathering doc outside main block. + INLINE_TEXT =3D 8 #: Reading the body of inline docs. =20 + #: Names for each parser state. name =3D [ "NORMAL", "NAME", @@ -253,9 +254,12 @@ class state: ] =20 =20 -SECTION_DEFAULT =3D "Description" # default section +SECTION_DEFAULT =3D "Description" #: Default section. =20 class KernelEntry: + """ + Encapsulates a Kernel documentation entry. + """ =20 def __init__(self, config, fname, ln): self.config =3D config @@ -288,9 +292,11 @@ class KernelEntry: # Management of section contents # def add_text(self, text): + """Add a new text to the entry contents list.""" self._contents.append(text) =20 def contents(self): + """Returns a string with all content texts that were added.""" return '\n'.join(self._contents) + '\n' =20 # TODO: rename to emit_message after removal of kernel-doc.pl @@ -309,10 +315,10 @@ class KernelEntry: self.warnings.append(log_msg) return =20 - # - # Begin a new section. - # def begin_section(self, line_no, title =3D SECTION_DEFAULT, dump =3D F= alse): + """ + Begin a new section. + """ if dump: self.dump_section(start_new =3D True) self.section =3D title @@ -366,11 +372,13 @@ class KernelDoc: documentation comments. """ =20 - # Section names - + #: Name of context section. section_context =3D "Context" + + #: Name of return section. section_return =3D "Return" =20 + #: String to write when a parameter is not described. undescribed =3D "-- undescribed --" =20 def __init__(self, config, fname): @@ -416,7 +424,7 @@ class KernelDoc: =20 def dump_section(self, start_new=3DTrue): """ - Dumps section contents to arrays/hashes intended for that purpose. + Dump section contents to arrays/hashes intended for that purpose. """ =20 if self.entry: @@ -425,9 +433,9 @@ class KernelDoc: # TODO: rename it to store_declaration after removal of kernel-doc.pl def output_declaration(self, dtype, name, **args): """ - Stores the entry into an entry array. + Store the entry into an entry array. =20 - The actual output and output filters will be handled elsewhere + The actual output and output filters will be handled elsewhere. """ =20 item =3D KdocItem(name, self.fname, dtype, @@ -663,10 +671,12 @@ class KernelDoc: self.emit_msg(ln, f"No description found for return value of '{dec= laration_name}'") =20 - # - # Split apart a structure prototype; returns (struct|union, name, memb= ers) or None - # def split_struct_proto(self, proto): + """ + Split apart a structure prototype; returns (struct|union, name, + members) or ``None``. + """ + type_pattern =3D r'(struct|union)' qualifiers =3D [ "__attribute__", @@ -685,21 +695,26 @@ class KernelDoc: if r.search(proto): return (r.group(1), r.group(3), r.group(2)) return None - # - # Rewrite the members of a structure or union for easier formatting la= ter on. - # Among other things, this function will turn a member like: - # - # struct { inner_members; } foo; - # - # into: - # - # struct foo; inner_members; - # + def rewrite_struct_members(self, members): + """ + Process ``struct``/``union`` members from the most deeply nested + outward. + + Rewrite the members of a ``struct`` or ``union`` for easier format= ting + later on. Among other things, this function will turn a member lik= e:: + + struct { inner_members; } foo; + + into:: + + struct foo; inner_members; + """ + # - # Process struct/union members from the most deeply nested outward= . The - # trick is in the ^{ below - it prevents a match of an outer struc= t/union - # until the inner one has been munged (removing the "{" in the pro= cess). + # The trick is in the ``^{`` below - it prevents a match of an out= er + # ``struct``/``union`` until the inner one has been munged + # (removing the ``{`` in the process). # struct_members =3D KernRe(r'(struct|union)' # 0: declaration type r'([^\{\};]+)' # 1: possible name @@ -777,11 +792,12 @@ class KernelDoc: tuples =3D struct_members.findall(members) return members =20 - # - # Format the struct declaration into a standard form for inclusion in = the - # resulting docs. - # def format_struct_decl(self, declaration): + """ + Format the ``struct`` declaration into a standard form for inclusi= on + in the resulting docs. + """ + # # Insert newlines, get rid of extra spaces. # @@ -815,7 +831,7 @@ class KernelDoc: =20 def dump_struct(self, ln, proto): """ - Store an entry for a struct or union + Store an entry for a ``struct`` or ``union`` """ # # Do the basic parse to get the pieces of the declaration. @@ -857,7 +873,7 @@ class KernelDoc: =20 def dump_enum(self, ln, proto): """ - Stores an enum inside self.entries array. + Store an ``enum`` inside self.entries array. """ # # Strip preprocessor directives. Note that this depends on the @@ -1004,7 +1020,7 @@ class KernelDoc: =20 def dump_declaration(self, ln, prototype): """ - Stores a data declaration inside self.entries array. + Store a data declaration inside self.entries array. """ =20 if self.entry.decl_type =3D=3D "enum": @@ -1021,7 +1037,7 @@ class KernelDoc: =20 def dump_function(self, ln, prototype): """ - Stores a function or function macro inside self.entries array. + Store a function or function macro inside self.entries array. """ =20 found =3D func_macro =3D False @@ -1122,7 +1138,7 @@ class KernelDoc: =20 def dump_typedef(self, ln, proto): """ - Stores a typedef inside self.entries array. + Store a ``typedef`` inside self.entries array. """ # # We start by looking for function typedefs. @@ -1176,7 +1192,7 @@ class KernelDoc: @staticmethod def process_export(function_set, line): """ - process EXPORT_SYMBOL* tags + process ``EXPORT_SYMBOL*`` tags =20 This method doesn't use any variable from the class, so declare it with a staticmethod decorator. @@ -1207,7 +1223,7 @@ class KernelDoc: =20 def process_normal(self, ln, line): """ - STATE_NORMAL: looking for the /** to begin everything. + STATE_NORMAL: looking for the ``/**`` to begin everything. """ =20 if not doc_start.match(line): @@ -1297,10 +1313,10 @@ class KernelDoc: else: self.emit_msg(ln, f"Cannot find identifier on line:\n{line}") =20 - # - # Helper function to determine if a new section is being started. - # def is_new_section(self, ln, line): + """ + Helper function to determine if a new section is being started. + """ if doc_sect.search(line): self.state =3D state.BODY # @@ -1332,10 +1348,10 @@ class KernelDoc: return True return False =20 - # - # Helper function to detect (and effect) the end of a kerneldoc commen= t. - # def is_comment_end(self, ln, line): + """ + Helper function to detect (and effect) the end of a kerneldoc comm= ent. + """ if doc_end.search(line): self.dump_section() =20 @@ -1354,7 +1370,7 @@ class KernelDoc: =20 def process_decl(self, ln, line): """ - STATE_DECLARATION: We've seen the beginning of a declaration + STATE_DECLARATION: We've seen the beginning of a declaration. """ if self.is_new_section(ln, line) or self.is_comment_end(ln, line): return @@ -1383,7 +1399,7 @@ class KernelDoc: =20 def process_special(self, ln, line): """ - STATE_SPECIAL_SECTION: a section ending with a blank line + STATE_SPECIAL_SECTION: a section ending with a blank line. """ # # If we have hit a blank line (only the " * " marker), then this @@ -1473,7 +1489,7 @@ class KernelDoc: =20 def syscall_munge(self, ln, proto): # pylint: disable=3DW0613 """ - Handle syscall definitions + Handle syscall definitions. """ =20 is_void =3D False @@ -1512,7 +1528,7 @@ class KernelDoc: =20 def tracepoint_munge(self, ln, proto): """ - Handle tracepoint definitions + Handle tracepoint definitions. """ =20 tracepointname =3D None @@ -1548,7 +1564,7 @@ class KernelDoc: return proto =20 def process_proto_function(self, ln, line): - """Ancillary routine to process a function prototype""" + """Ancillary routine to process a function prototype.""" =20 # strip C99-style comments to end of line line =3D KernRe(r"//.*$", re.S).sub('', line) @@ -1593,7 +1609,9 @@ class KernelDoc: self.reset_state(ln) =20 def process_proto_type(self, ln, line): - """Ancillary routine to process a type""" + """ + Ancillary routine to process a type. + """ =20 # Strip C99-style comments and surrounding whitespace line =3D KernRe(r"//.*$", re.S).sub('', line).strip() @@ -1647,7 +1665,7 @@ class KernelDoc: self.process_proto_type(ln, line) =20 def process_docblock(self, ln, line): - """STATE_DOCBLOCK: within a DOC: block.""" + """STATE_DOCBLOCK: within a ``DOC:`` block.""" =20 if doc_end.search(line): self.dump_section() @@ -1659,7 +1677,7 @@ class KernelDoc: =20 def parse_export(self): """ - Parses EXPORT_SYMBOL* macros from a single Kernel source file. + Parses ``EXPORT_SYMBOL*`` macros from a single Kernel source file. """ =20 export_table =3D set() @@ -1676,10 +1694,7 @@ class KernelDoc: =20 return export_table =20 - # - # The state/action table telling us which function to invoke in - # each state. - # + #: The state/action table telling us which function to invoke in each = state. state_actions =3D { state.NORMAL: process_normal, state.NAME: process_name, --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 985C02EA743; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=UH9pvtcHKCrUUWL4lM8baeE/vZI45ps/nSo0T0nOzu71dBpVPN6QvNL7Iv/5JKno2RxJL8MAjGTSRx7CBEocb1942GL80twrsN8q1zO/TctVqn89/KoOlAAYVHybVfwr0d632NJTHgJ7CLFnCtOw9R6hniSxr7FEGOJ2OSMGpGU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=FI+Dh9Iu2wtKz8NU+WdlvdtlEUg2nNsIV9O2y+kNbi8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=sLmbxONt8VjBq2EJJHLiVQ/7abkbvLIwG1Y4FQJuTsFHQS4/ON8XJ+8RTPILhZ16SkPIW1wbUXAWjzRUYIcRSAnnhXoiHNxtkYUz9/NU/uqxwC10UpMt6xZUtyaWY7yOZTn3TTidsnKXV3VdSzZzutpiSoXM3Nu23UTP+Inl/RY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=gd43tT/V; 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="gd43tT/V" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 265EFC2BCAF; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=FI+Dh9Iu2wtKz8NU+WdlvdtlEUg2nNsIV9O2y+kNbi8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=gd43tT/VzX+e0vhUUwiPFrf8umj+f8cr2Qt+AeCjbBnOWMe4e9vhyaABJDRaVtVfs iOe0xG4nSMd3VLempSi+HI1E7/4fDLZAULQtgeRBdRSCRx/mbf/3E8MDIUigSijJwz qoszrhzOH93MsuAHYjzvfcaD6pAaERwMKcGuxg3MloxmExOXpjsyfMnMEBIPYcbnrK ZAG4qYiwdBz46lIdkn1lBKdw/dOXydomOodp9OxwjxTfWm3GSG6ItPGrOmS7eARJhm lOLa7ZfECQTVgW7KbRf4r9Rth/GV8foo/n2rqbNzczo6mdaAb1UhZTuFxctN3cPcuk bwf6tJenqWl1g== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j20-1T4E; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH 10/25] docs: kdoc_output: Improve docstrings and comments Date: Mon, 19 Jan 2026 17:23:13 +0100 Message-ID: X-Mailer: git-send-email 2.52.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 In preparation to document kernel-doc module, improve its documentation. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 60 ++++++++++++++++------------ 1 file changed, 35 insertions(+), 25 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index d2bf94275d65..4210b91dde5f 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -5,14 +5,16 @@ # pylint: disable=3DC0301,R0902,R0911,R0912,R0913,R0914,R0915,R0917 =20 """ -Implement output filters to print kernel-doc documentation. +Classes to implement output filters to print kernel-doc documentation. =20 -The implementation uses a virtual base class (OutputFormat) which +The implementation uses a virtual base class ``OutputFormat``. It contains dispatches to virtual methods, and some code to filter out output messages. =20 The actual implementation is done on one separate class per each type -of output. Currently, there are output classes for ReST and man/troff. +of output, e.g. ``RestFormat`` and ``ManFormat`` classes. + +Currently, there are output classes for ReST and man/troff. """ =20 import os @@ -54,16 +56,19 @@ class OutputFormat: """ =20 # output mode. - OUTPUT_ALL =3D 0 # output all symbols and doc sections - OUTPUT_INCLUDE =3D 1 # output only specified symbols - OUTPUT_EXPORTED =3D 2 # output exported symbols - OUTPUT_INTERNAL =3D 3 # output non-exported symbols + OUTPUT_ALL =3D 0 #: Output all symbols and doc sections. + OUTPUT_INCLUDE =3D 1 #: Output only specified symbols. + OUTPUT_EXPORTED =3D 2 #: Output exported symbols. + OUTPUT_INTERNAL =3D 3 #: Output non-exported symbols. =20 - # Virtual member to be overridden at the inherited classes + #: Highlights to be used in ReST format. highlights =3D [] =20 + #: Blank line character. + blankline =3D "" + def __init__(self): - """Declare internal vars and set mode to OUTPUT_ALL""" + """Declare internal vars and set mode to ``OUTPUT_ALL``.""" =20 self.out_mode =3D self.OUTPUT_ALL self.enable_lineno =3D None @@ -128,7 +133,7 @@ class OutputFormat: self.config.warning(log_msg) =20 def check_doc(self, name, args): - """Check if DOC should be output""" + """Check if DOC should be output.""" =20 if self.no_doc_sections: return False @@ -177,7 +182,7 @@ class OutputFormat: =20 def msg(self, fname, name, args): """ - Handles a single entry from kernel-doc parser + Handles a single entry from kernel-doc parser. """ =20 self.data =3D "" @@ -220,30 +225,31 @@ class OutputFormat: # Virtual methods to be overridden by inherited classes # At the base class, those do nothing. def set_symbols(self, symbols): - """Get a list of all symbols from kernel_doc""" + """Get a list of all symbols from kernel_doc.""" =20 def out_doc(self, fname, name, args): - """Outputs a DOC block""" + """Outputs a DOC block.""" =20 def out_function(self, fname, name, args): - """Outputs a function""" + """Outputs a function.""" =20 def out_enum(self, fname, name, args): - """Outputs an enum""" + """Outputs an enum.""" =20 def out_var(self, fname, name, args): - """Outputs a variable""" + """Outputs a variable.""" =20 def out_typedef(self, fname, name, args): - """Outputs a typedef""" + """Outputs a typedef.""" =20 def out_struct(self, fname, name, args): - """Outputs a struct""" + """Outputs a struct.""" =20 =20 class RestFormat(OutputFormat): - """Consts and functions used by ReST output""" + """Consts and functions used by ReST output.""" =20 + #: Highlights to be used in ReST format highlights =3D [ (type_constant, r"``\1``"), (type_constant2, r"``\1``"), @@ -263,9 +269,13 @@ class RestFormat(OutputFormat): (type_fallback, r":c:type:`\1`"), (type_param_ref, r"**\1\2**") ] + blankline =3D "\n" =20 + #: Sphinx literal block regex. sphinx_literal =3D KernRe(r'^[^.].*::$', cache=3DFalse) + + #: Sphinx code block regex. sphinx_cblock =3D KernRe(r'^\.\.\ +code-block::', cache=3DFalse) =20 def __init__(self): @@ -280,7 +290,7 @@ class RestFormat(OutputFormat): self.lineprefix =3D "" =20 def print_lineno(self, ln): - """Outputs a line number""" + """Outputs a line number.""" =20 if self.enable_lineno and ln is not None: ln +=3D 1 @@ -289,7 +299,7 @@ class RestFormat(OutputFormat): def output_highlight(self, args): """ Outputs a C symbol that may require being converted to ReST using - the self.highlights variable + the self.highlights variable. """ =20 input_text =3D args @@ -570,7 +580,7 @@ class RestFormat(OutputFormat): =20 =20 class ManFormat(OutputFormat): - """Consts and functions used by man pages output""" + """Consts and functions used by man pages output.""" =20 highlights =3D ( (type_constant, r"\1"), @@ -587,6 +597,7 @@ class ManFormat(OutputFormat): ) blankline =3D "" =20 + #: Allowed timestamp formats. date_formats =3D [ "%a %b %d %H:%M:%S %Z %Y", "%a %b %d %H:%M:%S %Y", @@ -653,7 +664,7 @@ class ManFormat(OutputFormat): self.symbols =3D symbols =20 def out_tail(self, fname, name, args): - """Adds a tail for all man pages""" + """Adds a tail for all man pages.""" =20 # SEE ALSO section self.data +=3D f'.SH "SEE ALSO"' + "\n.PP\n" @@ -689,7 +700,7 @@ class ManFormat(OutputFormat): def output_highlight(self, block): """ Outputs a C symbol that may require being highlighted with - self.highlights variable using troff syntax + self.highlights variable using troff syntax. """ =20 contents =3D self.highlight_block(block) @@ -720,7 +731,6 @@ class ManFormat(OutputFormat): self.output_highlight(text) =20 def out_function(self, fname, name, args): - """output function in man""" =20 out_name =3D self.arg_name(args, name) =20 --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 98D9C2ED141; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=t5XDzEyc2WVf9YSUl8xEzq1BNbJFq5Rlx4vW5aP98QniAR+rC4+eePG+QfN3CYy7gK6kBNng67GRNAlbqL4bNkF1NBtwpLme0cjiwRbMculrOE22uLS+t8xezIa7dPmXXdkSzep/v6oiPIToB6xK8yd6Ti3Yq8D+FixvIetUvvw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=AT9QRc72PaX75+hy9TLUQhCbT/HxXyi982eiR6wBTwU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Za4/qOREt7AwAKgLw3tWXp0aPIBbUJwcVqPo4ZPfUmpjXaybnzaIwLDREc5I3wrvGUIbNADwog20g5rjM2fAJThJ3D+Wm/mR7IyYl/c0X9YhlUEJid110bqZN0dCxzarLBMi2aeLIko3bq2yux8GP9pvWzgAzOuBUN+xl16lGiM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=oUBhz+mE; 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="oUBhz+mE" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2E28BC2BCB2; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=AT9QRc72PaX75+hy9TLUQhCbT/HxXyi982eiR6wBTwU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=oUBhz+mE+VQypBJfENSOxgKBKsis1kBEXhuXOWOm1g2q+6qtbAEIHCfG3lDhax88Q EEPBWHPGaDGnwfIwUo4nmHMsvSfhudNf8I2vAsQI2sE0y1gKu9zSaoAEAGW63T5QLf z9rhp2MKN6mbEqJaC4kog4RU78rhTIv0Q3VUB5tgtrzora5uBIaJcHpj+5BL7W0Tc/ ayFSRfj0FbXXYNLStbV6D86M2CEfowTPQs/goRkjlLsblkwgSWRZcNLgDPvNIg6Fv/ UE8HTAyEO+N81bgFWp0RjOC8nHf+10ZaS2uGgC4329+5c/FYeu1thz5vcAQMXU7B1V G+/PPDODEJGhQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j24-1ZqU; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH 11/25] docs: kdoc_re: Improve docstrings and comments Date: Mon, 19 Jan 2026 17:23:14 +0100 Message-ID: <14a12a43144d52345bfd405d0401d246f0885acf.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 In preparation to document kernel-doc module, improve its documentation. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_re.py | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 2dfa1bf83d64..2816bd9f90f8 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -51,6 +51,9 @@ class KernRe: """ return self.regex.pattern =20 + def __repr__(self): + return f're.compile("{self.regex.pattern}")' + def __add__(self, other): """ Allows adding two regular expressions into one. @@ -61,7 +64,7 @@ class KernRe: =20 def match(self, string): """ - Handles a re.match storing its results + Handles a re.match storing its results. """ =20 self.last_match =3D self.regex.match(string) @@ -69,7 +72,7 @@ class KernRe: =20 def search(self, string): """ - Handles a re.search storing its results + Handles a re.search storing its results. """ =20 self.last_match =3D self.regex.search(string) @@ -77,28 +80,28 @@ class KernRe: =20 def findall(self, string): """ - Alias to re.findall + Alias to re.findall. """ =20 return self.regex.findall(string) =20 def split(self, string): """ - Alias to re.split + Alias to re.split. """ =20 return self.regex.split(string) =20 def sub(self, sub, string, count=3D0): """ - Alias to re.sub + Alias to re.sub. """ =20 return self.regex.sub(sub, string, count=3Dcount) =20 def group(self, num): """ - Returns the group results of the last match + Returns the group results of the last match. """ =20 return self.last_match.group(num) @@ -110,7 +113,7 @@ class NestedMatch: even harder on Python with its normal re module, as there are several advanced regular expressions that are missing. =20 - This is the case of this pattern: + This is the case of this pattern:: =20 '\\bSTRUCT_GROUP(\\(((?:(?>[^)(]+)|(?1))*)\\))[^;]*;' =20 @@ -121,6 +124,7 @@ class NestedMatch: replace nested expressions. =20 The original approach was suggested by: + https://stackoverflow.com/questions/5454322/python-how-to-match-ne= sted-parentheses-with-regex =20 Although I re-implemented it to make it more generic and match 3 types --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 6A3E829B228; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=QkX9/LQnZosxYtCvlB6tHFCGz53tDNM12jtrrwrCm81sM1c0wfi0q0zfjHYrKniZ22+LNtIBoUak5Xt78oG9igDcQkZFd+0+WVBawjeVrecp/oe9JrDlZUnUc/nKCUL1vRPDnknx5ijbjkyVPz4u09GkaU+AqvOfdjcj6NiCb88= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=i1tcZCaxJM2MU0fiO/S47vsflPzYkddGYteNjd18qHw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=d4bJ3AzBXlTI6sNfLK9SMrkWHEtPUb/MY0cfGHwblS+8LBL71rLeyB2whfBKYm954zhPExg26hu88haCkz4BZd+Ah+dzmIuNcyuEaQXXse5lzO+/vIS+pUf0Yw+iz32He1gzhHsUmqIxNCM1qzrcA/0M3chxjpMUaplAKgaT96Q= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=d69NExac; 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="d69NExac" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1D492C19425; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=i1tcZCaxJM2MU0fiO/S47vsflPzYkddGYteNjd18qHw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=d69NExacPxZ0Dv/g9MXpuB8KNYqUbDaN/faj7Wuh3UBiYZkvNsq3rwp7dtMGL8zKj 3R5e9F5pdNcLGxxJPFW1EHdKeC+YrRgnT2YynPkBqGLZ60oQ0ovfIgDBJb8NrDMCGk chmcPegiSt77KiLWRrxabNZBYpQgLDPS20oRUgW9lxgs4dR0x2qrztFUJn/eNELEb3 Ez1I+u2AEKONFm6NYLPPKcebHU+q2ckAuv4FGuK9FFXKnxMWgzuenX3E9mMe1y0AIp eJeca9oMxCExCqN1VAPsJuO9d9RuUBlLbq2qzipQWlng4LSXaoELeUGP4o9W6G7f6x 1jIYmGjTD1TXA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j28-1gfC; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 12/25] docs: kdoc: parse_data_structs: Improve docstrings and comments Date: Mon, 19 Jan 2026 17:23:15 +0100 Message-ID: <76ead85b4c13a8038180a792e270c3691d26cd25.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 In preparation to document kernel-doc module, improve its documentation. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/parse_data_structs.py | 62 +++++++++++++-------- 1 file changed, 39 insertions(+), 23 deletions(-) diff --git a/tools/lib/python/kdoc/parse_data_structs.py b/tools/lib/python= /kdoc/parse_data_structs.py index 25361996cd20..9941cd19032e 100755 --- a/tools/lib/python/kdoc/parse_data_structs.py +++ b/tools/lib/python/kdoc/parse_data_structs.py @@ -9,12 +9,12 @@ Parse a source file or header, creating ReStructured Text= cross references. It accepts an optional file to change the default symbol reference or to suppress symbols from the output. =20 -It is capable of identifying defines, functions, structs, typedefs, -enums and enum symbols and create cross-references for all of them. +It is capable of identifying ``define``, function, ``struct``, ``typedef``, +``enum`` and ``enum`` symbols and create cross-references for all of them. It is also capable of distinguish #define used for specifying a Linux ioctl. =20 -The optional rules file contains a set of rules like: +The optional rules file contains a set of rules like:: =20 ignore ioctl VIDIOC_ENUM_FMT replace ioctl VIDIOC_DQBUF vidioc_qbuf @@ -34,8 +34,8 @@ class ParseDataStructs: It is meant to allow having a more comprehensive documentation, where uAPI headers will create cross-reference links to the code. =20 - It is capable of identifying defines, functions, structs, typedefs, - enums and enum symbols and create cross-references for all of them. + It is capable of identifying ``define``, function, ``struct``, ``typed= ef``, + ``enum`` and ``enum`` symbols and create cross-references for all of t= hem. It is also capable of distinguish #define used for specifying a Linux ioctl. =20 @@ -43,13 +43,13 @@ class ParseDataStructs: allows parsing an exception file. Such file contains a set of rules using the syntax below: =20 - 1. Ignore rules: + 1. Ignore rules:: =20 ignore ` =20 Removes the symbol from reference generation. =20 - 2. Replace rules: + 2. Replace rules:: =20 replace =20 @@ -58,22 +58,22 @@ class ParseDataStructs: - A simple symbol name; - A full Sphinx reference. =20 - 3. Namespace rules + 3. Namespace rules:: =20 namespace =20 Sets C namespace to be used during cross-reference generation. Can be overridden by replace rules. =20 - On ignore and replace rules, can be: - - ioctl: for defines that end with _IO*, e.g. ioctl definitions - - define: for other defines - - symbol: for symbols defined within enums; - - typedef: for typedefs; - - enum: for the name of a non-anonymous enum; - - struct: for structs. + On ignore and replace rules, ```` can be: + - ``ioctl``: for defines that end with ``_IO*``, e.g. ioctl defini= tions + - ``define``: for other defines + - ``symbol``: for symbols defined within enums; + - ``typedef``: for typedefs; + - ``enum``: for the name of a non-anonymous enum; + - ``struct``: for structs. =20 - Examples: + Examples:: =20 ignore define __LINUX_MEDIA_H ignore ioctl VIDIOC_ENUM_FMT @@ -83,13 +83,15 @@ class ParseDataStructs: namespace MC """ =20 - # Parser regexes with multiple ways to capture enums and structs + #: Parser regex with multiple ways to capture enums. RE_ENUMS =3D [ re.compile(r"^\s*enum\s+([\w_]+)\s*\{"), re.compile(r"^\s*enum\s+([\w_]+)\s*$"), re.compile(r"^\s*typedef\s*enum\s+([\w_]+)\s*\{"), re.compile(r"^\s*typedef\s*enum\s+([\w_]+)\s*$"), ] + + #: Parser regex with multiple ways to capture structs. RE_STRUCTS =3D [ re.compile(r"^\s*struct\s+([_\w][\w\d_]+)\s*\{"), re.compile(r"^\s*struct\s+([_\w][\w\d_]+)$"), @@ -97,11 +99,13 @@ class ParseDataStructs: re.compile(r"^\s*typedef\s*struct\s+([_\w][\w\d_]+)$"), ] =20 - # FIXME: the original code was written a long time before Sphinx C + # NOTE: the original code was written a long time before Sphinx C # domain to have multiple namespaces. To avoid to much turn at the # existing hyperlinks, the code kept using "c:type" instead of the # right types. To change that, we need to change the types not only # here, but also at the uAPI media documentation. + + #: Dictionary containing C type identifiers to be transformed. DEF_SYMBOL_TYPES =3D { "ioctl": { "prefix": "\\ ", @@ -158,6 +162,10 @@ class ParseDataStructs: self.symbols[symbol_type] =3D {} =20 def read_exceptions(self, fname: str): + """ + Read an optional exceptions file, used to override defaults. + """ + if not fname: return =20 @@ -242,9 +250,9 @@ class ParseDataStructs: def store_type(self, ln, symbol_type: str, symbol: str, ref_name: str =3D None, replace_underscores: bool =3D T= rue): """ - Stores a new symbol at self.symbols under symbol_type. + Store a new symbol at self.symbols under symbol_type. =20 - By default, underscores are replaced by "-" + By default, underscores are replaced by ``-``. """ defs =3D self.DEF_SYMBOL_TYPES[symbol_type] =20 @@ -276,12 +284,16 @@ class ParseDataStructs: self.symbols[symbol_type][symbol] =3D (f"{prefix}{ref_link}{suffix= }", ln) =20 def store_line(self, line): - """Stores a line at self.data, properly indented""" + """ + Store a line at self.data, properly indented. + """ line =3D " " + line.expandtabs() self.data +=3D line.rstrip(" ") =20 def parse_file(self, file_in: str, exceptions: str =3D None): - """Reads a C source file and get identifiers""" + """ + Read a C source file and get identifiers. + """ self.data =3D "" is_enum =3D False is_comment =3D False @@ -433,7 +445,7 @@ class ParseDataStructs: =20 def gen_toc(self): """ - Create a list of symbols to be part of a TOC contents table + Create a list of symbols to be part of a TOC contents table. """ text =3D [] =20 @@ -464,6 +476,10 @@ class ParseDataStructs: return "\n".join(text) =20 def write_output(self, file_in: str, file_out: str, toc: bool): + """ + Write a ReST output file. + """ + title =3D os.path.basename(file_in) =20 if toc: --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 9882B2EB5CD; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=CLIv5aCHR8u+KguoYtgbt6416y+ed75BubFOEoPdZ62Abk0jIVtf234yz16IDJxIXz655aCODn2y20hjTlImm/G/Khyt7mMKGWAYYRj5q/CPEuoJr6rSCWH7b+zBXExn39uEJ6mwE8DHl+pTSDQAkeLnL4Ioa4HKSaVMLvjSFsU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=EJEpOIpo13K5wVlZXAiPofrL9GMVio3Ohn/l0ADAKD4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=nzC7qydKDtuQ1cxTLx9GRf9uy+zoHRzfmaeVXA01WtlEdG4vxLZK2vkDcdECY2KMjnCjGU4EgvL5ihGqvMF2NHc66OGw8nyFBoxNX2NCsUjv+c2+naPbFchRMLAllQtYavWc53b8ZlwWEZMl3a8UJBva/QJgKILQt/+dKPZu1sc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=jsbXdPfY; 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="jsbXdPfY" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3817CC2BCB8; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=EJEpOIpo13K5wVlZXAiPofrL9GMVio3Ohn/l0ADAKD4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jsbXdPfYVr7vvn9jt2ds1gbu7fFMcCtomVVJgVVhS/VNljROInlkd/XbYJ29K1eVP UX5X0P+L5zUp0LIbfWTfppMyfsKJ7oI/MMciaGEFsOryeMX6FDC/N9NbsuNhjCqjsd UKtyYxx+kBdJCefx+LpWBszmpzX5vQiHQopS5GAJoEE4BPT6X952Hjee0z0BfGiXJl 7aWM/H5EkOqze5LGOVaKWfAPwrgkYCJqJjmYf12Fe8uv2mOuTGg0xtrYThCjGrQI/D Rn9Nf1KFf5b1KdJtjadxFoZikumGMUKM9khHdZAEFm7Z7sGeGBE9KwdmxhHCOOoTX/ VAAf/1T+BnwyQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j2C-1nVz; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 13/25] docs: kdoc: enrich_formatter: Improve docstrings and comments Date: Mon, 19 Jan 2026 17:23:16 +0100 Message-ID: <55ec8b896fe00529d326859cd094230fb5a2cd30.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 In preparation to document kernel-doc module, improve its documentation. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/enrich_formatter.py | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/tools/lib/python/kdoc/enrich_formatter.py b/tools/lib/python/k= doc/enrich_formatter.py index bb171567a4ca..d1be4e5e1962 100644 --- a/tools/lib/python/kdoc/enrich_formatter.py +++ b/tools/lib/python/kdoc/enrich_formatter.py @@ -26,12 +26,16 @@ class EnrichFormatter(argparse.HelpFormatter): and how they're used at the __doc__ description. """ def __init__(self, *args, **kwargs): - """Initialize class and check if is TTY""" + """ + Initialize class and check if is TTY. + """ super().__init__(*args, **kwargs) self._tty =3D sys.stdout.isatty() =20 def enrich_text(self, text): - """Handle ReST markups (currently, only ``foo``)""" + r""" + Handle ReST markups (currently, only \`\`text\`\` markups). + """ if self._tty and text: # Replace ``text`` with ANSI SGR (bold) return re.sub(r'\`\`(.+?)\`\`', @@ -39,12 +43,16 @@ class EnrichFormatter(argparse.HelpFormatter): return text =20 def _fill_text(self, text, width, indent): - """Enrich descriptions with markups on it""" + """ + Enrich descriptions with markups on it. + """ enriched =3D self.enrich_text(text) return "\n".join(indent + line for line in enriched.splitlines()) =20 def _format_usage(self, usage, actions, groups, prefix): - """Enrich positional arguments at usage: line""" + """ + Enrich positional arguments at usage: line. + """ =20 prog =3D self._prog parts =3D [] @@ -63,7 +71,9 @@ class EnrichFormatter(argparse.HelpFormatter): return usage_text =20 def _format_action_invocation(self, action): - """Enrich argument names""" + """ + Enrich argument names. + """ if not action.option_strings: return self.enrich_text(f"``{action.dest.upper()}``") =20 --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 9B1812EDD41; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=bJieUhxnoOXye6TqkIaYiJvgSRdSkEVyxgST57jppBL74Zb3M9pc+xUpPNaa8LHnmZOnANOTxrX4wEAFalIlIGWsGxSInr/QoOPJztS4tb5bBT/J5R62TTlYlJl2pqianFycHIez7PCDNr9fTHUNOxfJZzZaWqyq41A5gfYwd+I= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=qeD2CxushaNmzGduOrZz2GnZPSRsopACODszEDevkew=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=O7btT67s9xnnZpcYn+lKWPZTy53iQ0o0myaxJXqjz+dptpnL3HNSHMY9qD5eFGYL7h7piUqDFXO20NPrQ+gUJckvU/Ez5P7aB3y+oY3RsoBt2FN/jO7hoqcekZuftufQTKpMyvrZu3h8Cmgd0ZVBSKSWcjlQs3Hv/23R/G9cLS4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=FL/Rov7J; 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="FL/Rov7J" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 38339C4AF09; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=qeD2CxushaNmzGduOrZz2GnZPSRsopACODszEDevkew=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FL/Rov7JMy4A6ix7Oo1u1qLeWW9LdMvhLtX9cUNWTS5iREN8O/g1WX/Tf/WUJp+tk ppcSAG6fy+XztkJs32f6sufN505nDNUdzteVk509VBUxaXdfm//nHuJj5xsaZ6nFgP WnwVZ171qetVVWiMH587n/9AZ+vQx2HCBuTCvJGXK563Osykik8Db4nl7Yb7T9Osky 1OcuyqK0I/5otobStGX1Qhuzmn5mPTiU69DiqK70/02gArVDpfB98tnoRHP8QjsQ1Y qVTKHhocZTY1xHkTxDc8fYn8axwz1nLDiGlJyzskF5bFXpZ/jZnJ0ui0FssGg2c5oK Jlxb5plJZrP4g== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j2G-1uOR; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH 14/25] docs: kdoc: python_version: Improve docstrings and comments Date: Mon, 19 Jan 2026 17:23:17 +0100 Message-ID: <2153afaeb496e1bb8d3cc318fff26c3f99d99486.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 In preparation to document kernel-doc module, improve its documentation. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/python_version.py | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/tools/lib/python/kdoc/python_version.py b/tools/lib/python/kdo= c/python_version.py index e83088013db2..4ddb7ead5f56 100644 --- a/tools/lib/python/kdoc/python_version.py +++ b/tools/lib/python/kdoc/python_version.py @@ -33,21 +33,31 @@ class PythonVersion: """ =20 def __init__(self, version): - """=C3=8Fnitialize self.version tuple from a version string""" + """ + =C3=8Fnitialize self.version tuple from a version string. + """ self.version =3D self.parse_version(version) =20 @staticmethod def parse_version(version): - """Convert a major.minor.patch version into a tuple""" + """ + Convert a major.minor.patch version into a tuple. + """ return tuple(int(x) for x in version.split(".")) =20 @staticmethod def ver_str(version): - """Returns a version tuple as major.minor.patch""" + """ + Returns a version tuple as major.minor.patch. + """ return ".".join([str(x) for x in version]) =20 @staticmethod def cmd_print(cmd, max_len=3D80): + """ + Outputs a command line, repecting maximum width. + """ + cmd_line =3D [] =20 for w in cmd: @@ -66,7 +76,9 @@ class PythonVersion: return "\n ".join(cmd_line) =20 def __str__(self): - """Returns a version tuple as major.minor.patch from self.version"= "" + """ + Return a version tuple as major.minor.patch from self.version. + """ return self.ver_str(self.version) =20 @staticmethod --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 BC23C2FBE1D; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=aMkGs6p8YraVdmnTaWs717TFNjuPNKXMAPqhrjH9Ys0D1CA9cEXqEbhHRpqqo+AdnM/bLx+tlOg6lSoVYTkL5PZfA9eZPOSd/tl649IuISIrFYuBflXvqvn0z6Dl4cQRczHZEqOPPwayfX/BRTFrqEOlYr82q80nR9BzA4YnHaQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=s1mjnTzuhsFarODXcVZv6x/pyTkp3qp8CK9/urSRqTw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=JMVFHZlxcbT4mo/B22MrZka7Bzw3cBcKAdsaRYGWAn8Ag/+rXwVVDydVTURywKHED5r57mw0vLyNwGAu7tdYTrRkvy32mXnYt1xjN3wBCT5cXWhp2IgeCPkMX2eQTNcptddK9rS22ephvmMzKhdxzKsIJTBpw/nuJzeV8AH3Mso= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=opIDcv+i; 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="opIDcv+i" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3E6F5C4AF0B; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=s1mjnTzuhsFarODXcVZv6x/pyTkp3qp8CK9/urSRqTw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=opIDcv+iX3GtIHbGZPS0pldZHcCVuuYq2fE38+qkU4QW01zbB9KP3XgwftfN4DoZI GG6fJZj6/ce5o5fCxuBa6ACLXzKNJCyw1UOxc1fv8v5fc41NSdgVP/WumS+N61euyS oaPB7yA3aECvyC7oGMrboR01FYZvasYrHTpawDIHEwWmbghLQm+x1dcGp7rOWU+cl0 l8mO/M09HUcQEY2fc+BuUzWAzmAqPtsgitkIJAOAgYb63gE4usgEoFtr19qGDu4oYt qqBAKyTsyEO7V26Sjs5deKhxb7cY2NQy8L16nT+zEVGcS9r9S26FkjVtSVs0li9Oru /C/44NfUBtznw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j2K-21He; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan Subject: [PATCH 15/25] docs: add kernel-doc modules documentation Date: Mon, 19 Jan 2026 17:23:18 +0100 Message-ID: <88ac2d82a45718c4e27aefac831586a71204ebf2.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 Place kernel-doc modules documentation at Linux Kernel docs. Signed-off-by: Mauro Carvalho Chehab --- Documentation/tools/index.rst | 1 + Documentation/tools/kdoc.rst | 12 +++++++ Documentation/tools/kdoc_ancillary.rst | 46 ++++++++++++++++++++++++++ Documentation/tools/kdoc_output.rst | 14 ++++++++ Documentation/tools/kdoc_parser.rst | 29 ++++++++++++++++ Documentation/tools/python.rst | 10 ++++++ 6 files changed, 112 insertions(+) create mode 100644 Documentation/tools/kdoc.rst create mode 100644 Documentation/tools/kdoc_ancillary.rst create mode 100644 Documentation/tools/kdoc_output.rst create mode 100644 Documentation/tools/kdoc_parser.rst create mode 100644 Documentation/tools/python.rst diff --git a/Documentation/tools/index.rst b/Documentation/tools/index.rst index 80488e290e10..89b81a13c6a1 100644 --- a/Documentation/tools/index.rst +++ b/Documentation/tools/index.rst @@ -12,6 +12,7 @@ more additions are needed here: =20 rtla/index rv/index + python =20 .. only:: subproject and html =20 diff --git a/Documentation/tools/kdoc.rst b/Documentation/tools/kdoc.rst new file mode 100644 index 000000000000..e51ba159d8c4 --- /dev/null +++ b/Documentation/tools/kdoc.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Kernel-doc modules +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. toctree:: + :maxdepth: 2 + + kdoc_parser + kdoc_output + kdoc_ancillary diff --git a/Documentation/tools/kdoc_ancillary.rst b/Documentation/tools/k= doc_ancillary.rst new file mode 100644 index 000000000000..3950d0a3f104 --- /dev/null +++ b/Documentation/tools/kdoc_ancillary.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Ancillary classes +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Argparse formatter class +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. automodule:: lib.python.kdoc.enrich_formatter + :members: + :show-inheritance: + :undoc-members: + +Regular expression class handler +=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=3D + +.. automodule:: lib.python.kdoc.kdoc_re + :members: + :show-inheritance: + :undoc-members: + + +Chinese, Japanese and Korean variable fonts handler +=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=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D + +.. automodule:: lib.python.kdoc.latex_fonts + :members: + :show-inheritance: + :undoc-members: + +Kernel C file include logic +=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 + +.. automodule:: lib.python.kdoc.parse_data_structs + :members: + :show-inheritance: + :undoc-members: + +Python version ancillary methods +=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=3D + +.. automodule:: lib.python.kdoc.python_version + :members: + :show-inheritance: + :undoc-members: diff --git a/Documentation/tools/kdoc_output.rst b/Documentation/tools/kdoc= _output.rst new file mode 100644 index 000000000000..08fd271ec556 --- /dev/null +++ b/Documentation/tools/kdoc_output.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Kernel-doc output stage +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Output handler for man pages and ReST +=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=3D=3D=3D=3D=3D=3D + +.. automodule:: lib.python.kdoc.kdoc_output + :members: + :show-inheritance: + :undoc-members: + diff --git a/Documentation/tools/kdoc_parser.rst b/Documentation/tools/kdoc= _parser.rst new file mode 100644 index 000000000000..03ee54a1b1cc --- /dev/null +++ b/Documentation/tools/kdoc_parser.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Kernel-doc parser stage +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +File handler classes +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. automodule:: lib.python.kdoc.kdoc_files + :members: + :show-inheritance: + :undoc-members: + +Parsed item data class +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. automodule:: lib.python.kdoc.kdoc_item + :members: + :show-inheritance: + :undoc-members: + +Parser classes and methods +=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 + +.. automodule:: lib.python.kdoc.kdoc_parser + :members: + :show-inheritance: + :undoc-members: diff --git a/Documentation/tools/python.rst b/Documentation/tools/python.rst new file mode 100644 index 000000000000..e826787ce9dd --- /dev/null +++ b/Documentation/tools/python.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Python libraries +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. toctree:: + :maxdepth: 4 + + kdoc --=20 2.52.0 From nobody Sat Feb 7 20:57:56 2026 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 BBCA02FB093; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=VMPSrL/2VQxv8kKNrFTWBFujC9f/noBImtCn94Zrb9NF9JQ/gj725od3lBHXapSFscG14oeiNJqbGHAAi5h7jzz8BfNFKqtQhndona4QmH3JkNNLi7tSIj7Trf6hmDIAWzuN4seNRWkZkMV1TL8AGhPmr2VmYhHoUl0WmreTxfs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=exx7FqZl941FZsZhtYfKeTVwWdKc6AHLhML71ImEVTk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=oNXJBk1G54pyiWFxEaKhY3ghT768kfKo294Iebrnv3gydxZSILPEDbMULaeX2cJCLJNDXq87pBzgoJDLuapeVVsxhCRETTkBMjWzrmlNJpX5GAjxb3DQrQV0klLlUZajzhVkJxZ5Lo/NV6BUbQ0MW/37026Zl8Hnjn5YhQ6Eqh4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=V6ZJzBFx; 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="V6ZJzBFx" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3E1AFC2BCC4; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=exx7FqZl941FZsZhtYfKeTVwWdKc6AHLhML71ImEVTk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=V6ZJzBFxN+RV5gpEo1KC0DrHBaeS3mKpanr3wyS2b6VLloW36+fqEpzRzk7kTqQ6d AvQr80+9Ry85SmPRWe4HSdg3YkWpE/+qS0Z+ZMVOmDEvrRb7FtRgGj1U80o6dVjk/p ZkvaWfwkny2qvHLnXEp3dnyTzdUkVEu3BvI96rrEJ12DBocJjnETnxN759nINlOGoZ SyiTGWFVG+eOXDNiQXpOk3f0/LCUWo0lQdRLaJs6cas/ilD14XlOy3zUtkneJAV5yS AfbNUb60b66nmJXA+gzGzcM0yfiv2zZcnfoEO1gzHjU4JTvBPaoMU/u/Aso+2BYqAg Y6Ekf//U8ca/g== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j2O-286m; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan Subject: [PATCH 16/25] docs: add kabi modules documentation Date: Mon, 19 Jan 2026 17:23:19 +0100 Message-ID: X-Mailer: git-send-email 2.52.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 Place kernel abi modules documentation at Linux Kernel docs. Signed-off-by: Mauro Carvalho Chehab --- Documentation/tools/kabi.rst | 13 +++++++++++++ Documentation/tools/kabi_helpers.rst | 11 +++++++++++ Documentation/tools/kabi_parser.rst | 10 ++++++++++ Documentation/tools/kabi_regex.rst | 10 ++++++++++ Documentation/tools/kabi_symbols.rst | 10 ++++++++++ Documentation/tools/python.rst | 1 + 6 files changed, 55 insertions(+) create mode 100644 Documentation/tools/kabi.rst create mode 100644 Documentation/tools/kabi_helpers.rst create mode 100644 Documentation/tools/kabi_parser.rst create mode 100644 Documentation/tools/kabi_regex.rst create mode 100644 Documentation/tools/kabi_symbols.rst diff --git a/Documentation/tools/kabi.rst b/Documentation/tools/kabi.rst new file mode 100644 index 000000000000..92812a20fcf7 --- /dev/null +++ b/Documentation/tools/kabi.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.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=3D=3D=3D=3D=3D=3D +Kernel ABI documentation tool modules +=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=3D=3D=3D=3D=3D=3D + +.. toctree:: + :maxdepth: 2 + + kabi_parser + kabi_regex + kabi_symbols + kabi_helpers diff --git a/Documentation/tools/kabi_helpers.rst b/Documentation/tools/kab= i_helpers.rst new file mode 100644 index 000000000000..5c6ec6081500 --- /dev/null +++ b/Documentation/tools/kabi_helpers.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Ancillary classes +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. automodule:: lib.python.abi.helpers + :members: + :member-order: bysource + :show-inheritance: + :undoc-members: diff --git a/Documentation/tools/kabi_parser.rst b/Documentation/tools/kabi= _parser.rst new file mode 100644 index 000000000000..95826da21b3d --- /dev/null +++ b/Documentation/tools/kabi_parser.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.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=3D=3D=3D=3D=3D=3D +Kernel ABI documentation parser class +=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=3D=3D=3D=3D=3D=3D + +.. automodule:: lib.python.abi.abi_parser + :members: + :show-inheritance: + :undoc-members: diff --git a/Documentation/tools/kabi_regex.rst b/Documentation/tools/kabi_= regex.rst new file mode 100644 index 000000000000..bfc3a0d91c47 --- /dev/null +++ b/Documentation/tools/kabi_regex.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.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 +ABI regex search symbol class +=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 + +.. automodule:: lib.python.abi.abi_regex + :members: + :show-inheritance: + :undoc-members: diff --git a/Documentation/tools/kabi_symbols.rst b/Documentation/tools/kab= i_symbols.rst new file mode 100644 index 000000000000..c75a9380f89f --- /dev/null +++ b/Documentation/tools/kabi_symbols.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.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=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +System ABI documentation validation class +=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=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. automodule:: lib.python.abi.system_symbols + :members: + :show-inheritance: + :undoc-members: diff --git a/Documentation/tools/python.rst b/Documentation/tools/python.rst index e826787ce9dd..978298fba6d3 100644 --- a/Documentation/tools/python.rst +++ b/Documentation/tools/python.rst @@ -8,3 +8,4 @@ Python libraries :maxdepth: 4 =20 kdoc + kabi --=20 2.52.0 From nobody Sat Feb 7 20:57:57 2026 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 BC8372FD7D5; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=FzLet2oon4YZGMioZPiy2fKItDFOQaUdJ7fBlsqshlDQcjNvtdSGl1wx4lTwNtMzfYHEXIUzPELrPsPCGVSxjbRRgCyfjJwPp6owKEeBtAXTMb7gQRGgiWU0fwIKMfE51gbkGjKVA3TdXl3ckCa07Ki3/jfTo51sOE0OrMXqss0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=tfVDmQ1gX9VG9PNgXAXt4hYgxcfeRlZft7aVQXVoK88=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=utUPy3G+YVmzGNmv5bzJHp/u36w+tjWGT2fZ47rkfDokVT0lWLCLNJNP+Lvs+sYtQSgzGzG886zf/3coEuUbPf7lvN7rH5laL3q4ZlSHZyvaz/ngdTOpiknLzWx4/+VIyDv703SlBS5gQVPSg1ILPY6MDXQxbNpnTYijXl8Ry9E= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ROCZdxLq; 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="ROCZdxLq" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3F8DEC2BCC9; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=tfVDmQ1gX9VG9PNgXAXt4hYgxcfeRlZft7aVQXVoK88=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ROCZdxLqd7TRMtN7NYdj0WL6tefWkBjzaduO1JD5v+6xy09BEGq+2erKGUgkWf+6G GUWPMTZ084Ng5YNv/wczwYTIFI3PHnyrBLX13lkKa0oB6Kvgxiv+nVNigBTrqEZnr5 u1WSFfu4pjPlch76mtdNIHMRcU7XmnGkjbFaz1cu/X76iJUfKLyXCeCquU4wyRMzJj 0p4k953VSA3dn5CH9qen/paM306PQf0Xw+KBoFqzQybrk4ZpaVHkmGwy1KQ2W0DKOZ nBb4VPttT0KvswKlGOPzwHyLm0S9XVC9B8yQ32Cm+SfFVW5d9WZxTxxPt6qWf4TPrV 1UgTG2pGyN7Xw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j2S-2ErO; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 17/25] docs: python: abi_parser: do some improvements at documentation Date: Mon, 19 Jan 2026 17:23:20 +0100 Message-ID: X-Mailer: git-send-email 2.52.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 Add documentation for two consts and ensure that all sentenses will end with a dot. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/abi/abi_parser.py | 33 ++++++++++++++++-------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/tools/lib/python/abi/abi_parser.py b/tools/lib/python/abi/abi_= parser.py index 9b8db70067ef..d7bb20ef3acc 100644 --- a/tools/lib/python/abi/abi_parser.py +++ b/tools/lib/python/abi/abi_parser.py @@ -21,14 +21,17 @@ from abi.helpers import AbiDebug, ABI_DIR =20 =20 class AbiParser: - """Main class to parse ABI files""" + """Main class to parse ABI files.""" =20 + #: Valid tags at Documentation/ABI. TAGS =3D r"(what|where|date|kernelversion|contact|description|users)" + + #: ABI elements that will auto-generate cross-references. XREF =3D r"(?:^|\s|\()(\/(?:sys|config|proc|dev|kvd)\/[^,.:;\)\s]+)(?:= [,.:;\)\s]|\Z)" =20 def __init__(self, directory, logger=3DNone, enable_lineno=3DFalse, show_warnings=3DTrue, debug=3D0): - """Stores arguments for the class and initialize class vars""" + """Stores arguments for the class and initialize class vars.""" =20 self.directory =3D directory self.enable_lineno =3D enable_lineno @@ -65,7 +68,7 @@ class AbiParser: self.re_xref_node =3D re.compile(self.XREF) =20 def warn(self, fdata, msg, extra=3DNone): - """Displays a parse error if warning is enabled""" + """Displays a parse error if warning is enabled.""" =20 if not self.show_warnings: return @@ -77,7 +80,7 @@ class AbiParser: self.log.warning(msg) =20 def add_symbol(self, what, fname, ln=3DNone, xref=3DNone): - """Create a reference table describing where each 'what' is locate= d""" + """Create a reference table describing where each 'what' is locate= d.""" =20 if what not in self.what_symbols: self.what_symbols[what] =3D {"file": {}} @@ -92,7 +95,7 @@ class AbiParser: self.what_symbols[what]["xref"] =3D xref =20 def _parse_line(self, fdata, line): - """Parse a single line of an ABI file""" + """Parse a single line of an ABI file.""" =20 new_what =3D False new_tag =3D False @@ -264,7 +267,7 @@ class AbiParser: self.warn(fdata, "Unexpected content", line) =20 def parse_readme(self, nametag, fname): - """Parse ABI README file""" + """Parse ABI README file.""" =20 nametag["what"] =3D ["Introduction"] nametag["path"] =3D "README" @@ -282,7 +285,7 @@ class AbiParser: nametag["description"] +=3D line =20 def parse_file(self, fname, path, basename): - """Parse a single file""" + """Parse a single file.""" =20 ref =3D f"abi_file_{path}_{basename}" ref =3D self.re_unprintable.sub("_", ref).strip("_") @@ -348,7 +351,7 @@ class AbiParser: self.add_symbol(what=3Dw, fname=3Dfname, xref=3Dfdata.= key) =20 def _parse_abi(self, root=3DNone): - """Internal function to parse documentation ABI recursively""" + """Internal function to parse documentation ABI recursively.""" =20 if not root: root =3D self.directory @@ -377,7 +380,7 @@ class AbiParser: self.parse_file(name, path, basename) =20 def parse_abi(self, root=3DNone): - """Parse documentation ABI""" + """Parse documentation ABI.""" =20 self._parse_abi(root) =20 @@ -385,7 +388,7 @@ class AbiParser: self.log.debug(pformat(self.data)) =20 def desc_txt(self, desc): - """Print description as found inside ABI files""" + """Print description as found inside ABI files.""" =20 desc =3D desc.strip(" \t\n") =20 @@ -393,7 +396,7 @@ class AbiParser: =20 def xref(self, fname): """ - Converts a Documentation/ABI + basename into a ReST cross-reference + Converts a Documentation/ABI + basename into a ReST cross-referenc= e. """ =20 xref =3D self.file_refs.get(fname) @@ -403,7 +406,7 @@ class AbiParser: return xref =20 def desc_rst(self, desc): - """Enrich ReST output by creating cross-references""" + """Enrich ReST output by creating cross-references.""" =20 # Remove title markups from the description # Having titles inside ABI files will only work if extra @@ -459,7 +462,7 @@ class AbiParser: =20 def doc(self, output_in_txt=3DFalse, show_symbols=3DTrue, show_file=3D= True, filter_path=3DNone): - """Print ABI at stdout""" + """Print ABI at stdout.""" =20 part =3D None for key, v in sorted(self.data.items(), @@ -549,7 +552,7 @@ class AbiParser: yield (msg, file_ref[0][0], ln) =20 def check_issues(self): - """Warn about duplicated ABI entries""" + """Warn about duplicated ABI entries.""" =20 for what, v in self.what_symbols.items(): files =3D v.get("file") @@ -575,7 +578,7 @@ class AbiParser: self.log.warning("%s is defined %d times: %s", what, len(f), "= ; ".join(f)) =20 def search_symbols(self, expr): - """ Searches for ABI symbols """ + """ Searches for ABI symbols.""" =20 regex =3D re.compile(expr, re.I) =20 --=20 2.52.0 From nobody Sat Feb 7 20:57:57 2026 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 BC8B52FE05D; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=WbvhmiAI+soPtoPE/cPslUCVAhzDEYdm/HbBOFt1bM//wqFfxBAHrmFj9Ep+eUuIlNBhbAtWbH0jKAh+LyVieTbHdh0RpwkS96J4eowRPrlinHIa/fopM/iLoBhILwMSxZFuxGBOQJ52DYZ8GV+BPb+vKYBn1guRy8rwI6IkupM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=8E4r/s6Y7smA5NIglr3ktHdSZHhdGR4bBEvyzy03zT8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=QyD+nmunfv8lDfQ2uSLrhk//iy7Z4bZB5qlM2CyhAWg25/SqCv/Fngia/eVg51c8iJihB3cytiYKO1kmZUrpBkdbNjwd7wjJqHMmUHYcMG60Qw6YUXZ2wkDk509YquYm2ElSUiPcPhrHEicJjmpC+iblY95O78rMh80OVIoBzis= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=GvCJSL7f; 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="GvCJSL7f" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4DB7AC2BCFC; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=8E4r/s6Y7smA5NIglr3ktHdSZHhdGR4bBEvyzy03zT8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GvCJSL7fFUz/LtAB3A2ZK+UEpWTUHPg6vLV92P46b+XbI5ddHsZfGM8GnXJ46wd0R IjWlQXqOhDalkiv2OuAeQwODkSTtp0qXfdGSZSD+lc4m+WChCYQ0IjGJ9f7YgbCMfy IhLUPxZ/ceIWwy6k0H7jDQMAbIfmcbi8tx0sQbY2DHplmhaEmHljQ8jyQUMZVTNm0Q yrmBInbPWsk8SrKofn4VXBtX2WPPb2ip5EraC2XWYPBcKpNhpRkTM2KdvDL8oRDIsk UPbaP4LVIbYCz3M//Tze12gZsOQGZO65cQvWxa5rD8ktsPnj/ngHTZ/xTJ3zsNHKtY l3AkJ8xSna+nA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j2W-2Lkp; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 18/25] docs: python: abi_regex: do some improvements at documentation Date: Mon, 19 Jan 2026 17:23:21 +0100 Message-ID: <5419ad89a5042c1571198c2f055866674808579b.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 Add documentation for two consts and ensure that all sentenses will end with a dot. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/abi/abi_regex.py | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/tools/lib/python/abi/abi_regex.py b/tools/lib/python/abi/abi_r= egex.py index d5553206de3c..d0c5e3ede6b5 100644 --- a/tools/lib/python/abi/abi_regex.py +++ b/tools/lib/python/abi/abi_regex.py @@ -16,10 +16,22 @@ from abi.abi_parser import AbiParser from abi.helpers import AbiDebug =20 class AbiRegex(AbiParser): - """Extends AbiParser to search ABI nodes with regular expressions""" + """ + Extends AbiParser to search ABI nodes with regular expressions. =20 - # Escape only ASCII visible characters + There some optimizations here to allow a quick symbol search: + instead of trying to place all symbols altogether an doing linear + search which is very time consuming, create a tree with one depth, + grouping similar symbols altogether. + + Yet, sometimes a full search will be needed, so we have a special bran= ch + on such group tree where other symbols are placed. + """ + + #: Escape only ASCII visible characters. escape_symbols =3D r"([\x21-\x29\x2b-\x2d\x3a-\x40\x5c\x60\x7b-\x7e])" + + #: Special group for other nodes. leave_others =3D "others" =20 # Tuples with regular expressions to be compiled and replacement data @@ -88,13 +100,15 @@ class AbiRegex(AbiParser): # Recover plus characters (re.compile(r"\xf7"), "+"), ] + + #: Regex to check if the symbol name has a number on it. re_has_num =3D re.compile(r"\\d") =20 - # Symbol name after escape_chars that are considered a devnode basename + #: Symbol name after escape_chars that are considered a devnode basena= me. re_symbol_name =3D re.compile(r"(\w|\\[\.\-\:])+$") =20 - # List of popular group names to be skipped to minimize regex group si= ze - # Use AbiDebug.SUBGROUP_SIZE to detect those + #: List of popular group names to be skipped to minimize regex group s= ize + #: Use AbiDebug.SUBGROUP_SIZE to detect those. skip_names =3D set(["devices", "hwmon"]) =20 def regex_append(self, what, new): @@ -148,7 +162,7 @@ class AbiRegex(AbiParser): def get_regexes(self, what): """ Given an ABI devnode, return a list of all regular expressions that - may match it, based on the sub-groups created by regex_append() + may match it, based on the sub-groups created by regex_append(). """ =20 re_list =3D [] --=20 2.52.0 From nobody Sat Feb 7 20:57:57 2026 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 BF9362FFDD6; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=hQ9+dkMPxHSAlA3G5Cp4NsQJdKaHK2xWEvtK0JVGXuT8gai0XD2jkAhJcG/PbsJpNTiyNrSoQzkmxpMr9OoSohntgKtmEVVqzgzN9R5ct5M1XapkpPJcdUKuv9dna5iKrql+p5GQfwoZYQ7L9R0vK6w4euKJsLpigZpo8kFiFMA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=vD2wOczQTMyK8eBInsPg/A/L1CMB+IhGbdrLcMRyq0M=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=DsAhLYv2ThThOKWJEUUKfK5sBi6d95AJywFNR8121Z8kvOm+i8BvsN6pSJ44GYV7yUYaab6A//qD5FHJFsJf/HbTsiQzgmCTakvikNJ1WWe/M3UU3Fli9JWQLE10fM9C+bVRIehkJNp727qEJkJnkkoJOUICk1yssyVBgR6Z7ic= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=sRp1g37/; 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="sRp1g37/" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4B4BEC2BCB6; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=vD2wOczQTMyK8eBInsPg/A/L1CMB+IhGbdrLcMRyq0M=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sRp1g37/1JO2xhTb25DKM8UcASOgLnA+U+o3wzGw0oLvlDJ5+p9SYowXD7+6CSGRP HVVSBIUy5EbUtexKNaBQyZ/BWAJxe38rUZZdPZkrwcqEZTiQh7/8Y4l6bZfzDzeK22 IJ1brBdMAw/iuHL6l0VWzClzMzMBlUrI8Nmb2X7ES9dKl/URIlRO4SwU9RKnwDAiAJ w9TuIuxFc/wGmy0rwTzwzfFwxjMh2fDLC/HPvnLzVeuH8V5DM35sKE/lHqwzJTQcDe HQyL6zLoEXRwRBEPcAAVnM43nWQurOzZAoEAlNPITpoltANQ7FzNdLN3HexfGz9xBu 9/YRhlkqc/KSA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j2a-2SU2; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 19/25] docs: kabi: system_symbols: end docstring phrases with a dot Date: Mon, 19 Jan 2026 17:23:22 +0100 Message-ID: X-Mailer: git-send-email 2.52.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 Some docstring classes are not ending with a dot. Fix to make it more uniform. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/abi/system_symbols.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/tools/lib/python/abi/system_symbols.py b/tools/lib/python/abi/= system_symbols.py index 4a2554da217b..7bbefd274ea2 100644 --- a/tools/lib/python/abi/system_symbols.py +++ b/tools/lib/python/abi/system_symbols.py @@ -18,11 +18,11 @@ from random import shuffle from abi.helpers import AbiDebug =20 class SystemSymbols: - """Stores arguments for the class and initialize class vars""" + """Stores arguments for the class and initialize class vars.""" =20 def graph_add_file(self, path, link=3DNone): """ - add a file path to the sysfs graph stored at self.root + add a file path to the sysfs graph stored at self.root. """ =20 if path in self.files: @@ -43,7 +43,7 @@ class SystemSymbols: self.files.add(path) =20 def print_graph(self, root_prefix=3D"", root=3DNone, level=3D0): - """Prints a reference tree graph using UTF-8 characters""" + """Prints a reference tree graph using UTF-8 characters.""" =20 if not root: root =3D self.root @@ -173,7 +173,7 @@ class SystemSymbols: self._walk(sysfs) =20 def check_file(self, refs, found): - """Check missing ABI symbols for a given sysfs file""" + """Check missing ABI symbols for a given sysfs file.""" =20 res_list =3D [] =20 @@ -214,7 +214,7 @@ class SystemSymbols: return res_list =20 def _ref_interactor(self, root): - """Recursive function to interact over the sysfs tree""" + """Recursive function to interact over the sysfs tree.""" =20 for k, v in root.items(): if isinstance(v, dict): @@ -232,7 +232,7 @@ class SystemSymbols: =20 =20 def get_fileref(self, all_refs, chunk_size): - """Interactor to group refs into chunks""" + """Interactor to group refs into chunks.""" =20 n =3D 0 refs =3D [] @@ -250,7 +250,7 @@ class SystemSymbols: =20 def check_undefined_symbols(self, max_workers=3DNone, chunk_size=3D50, found=3DNone, dry_run=3DNone): - """Seach ABI for sysfs symbols missing documentation""" + """Seach ABI for sysfs symbols missing documentation.""" =20 self.abi.parse_abi() =20 --=20 2.52.0 From nobody Sat Feb 7 20:57:57 2026 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 BBEFC2FBE0A; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=EVz/UXJXUO77Jw+Oe7a9fJmsRwlv045yHSdFS0Y/bYM1DYrWkqzIHunijrjuY7X0FhYjo/t4+0ergrop0ORhBMBO3v/C8YnNow6M8DttAWicIAeROllZiB/fWqa2aKc4nOU4uMRjVlo81xjdvYRBdRU9gp6NIPPH0tMTMRtt/7Q= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=6uS4eQG9ngB34Mkx8eLKHA6/k7ERydcb0HVTVQ6Jz0M=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=r6jgaZivQtmSuHfbzRqKbiNzxi6aSuwzBkvpg0SzHSMyCFGf4ALoPxyHMN9JrNPtYjc23DJMNCokc3Mx/BNTzo+Qx7U5GRwDp2PoxcoW7UfavO0L3w5UMf7RxdkFLhkcDqI8a2vH2jpkvQOiOZkkxzQVrZR0LOZQmCXLdFDIrPs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ZG3re5R9; 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="ZG3re5R9" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 52950C32781; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=6uS4eQG9ngB34Mkx8eLKHA6/k7ERydcb0HVTVQ6Jz0M=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZG3re5R95+lkt/qNBGewr4f9dnG2u+CFq1LXLJWWiQ/UU/d9iygGnyZA68b/SoDZ/ v/N+LuKNo+iJUVHKpqlXiPuoFU6r2H22rnXIY4J2Diw6xKlDGR4I0ulOU2xCUvkz0f zMQ64pUYkj6fYP5k0bT+Z3J7vpHmtzkbo1SmZOBERPypt9WFs+XAGTzuK4XYes1G2Q Ah/6q2GPQRqYOaWE6iv4fZG8rV/E4wA/pu2v5hfUzXx0fdAWE5qbGkdfv13BVTHEEW wID5eBU3fdM/qp2UbJBtzrLxqYHWtK3RH+mZpni/Y/GEzgpdo1uVcguMfU885yvmZK yPPZFedrvkDvQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j2e-2ZI9; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 20/25] docs: kabi: helpers: add helper for debug bits 7 and 8 Date: Mon, 19 Jan 2026 17:23:23 +0100 Message-ID: <60e99b9060396eac8621954d6b8a73af45df90fb.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 The kabi logic supports 8 debug bits, but only 6 are currently documented. Document the remaining ones. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/abi/helpers.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tools/lib/python/abi/helpers.py b/tools/lib/python/abi/helpers= .py index 639b23e4ca33..b8c8dfb1272e 100644 --- a/tools/lib/python/abi/helpers.py +++ b/tools/lib/python/abi/helpers.py @@ -35,4 +35,6 @@ DEBUG_HELP =3D """ 16 - enable debug for what to regex conversion 32 - enable debug for symbol regex subgroups 64 - enable debug for sysfs graph tree variable +128 - enable debug of search groups +256 - enable displaying refrence tree graphs for undefined symbols. """ --=20 2.52.0 From nobody Sat Feb 7 20:57:57 2026 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 BDB592FE593; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=Ohl177sDMwCsE57ZmX1E54LTHJEaUDsDth+QMuYyAPOy5vvGj48O3ERrBhKEo4z/rEMTSO96XVg+QQFFIGui/7UpME0OXObP7+aYEMMGX8YteOnDW8nbiAcZgi09eJUjRGWH08jaX/bYsW2FZUZ7kZjnNmEagV4KJOTCSCLSJqA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=AVd8fmGIAF4zYlsPWk9dKYgZxAbzv6350/TY3F2WP6Y=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=jTRlKsmOI+Ea3VdJr3UC+NfLSty7lFGcZR29qYomx7VNdiHIp5JoqyHs7jTGeJ34xXR9YdyEn/xfLRhTm5HmHLepTLwCIrEazqGNP+3yjKwLPfX7/7/QYc4b6ZGXJ+WgGd3bu+2j87aEeH8x4qwa98qMcpHA0ErSKZsAwB5NMjc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Hle9N8Af; 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="Hle9N8Af" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5A836C32786; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=AVd8fmGIAF4zYlsPWk9dKYgZxAbzv6350/TY3F2WP6Y=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Hle9N8Afd4V6xcMwvLV+zZK3thQALTyt7JP1o9URfKXdPq6Mau9maQPTph7KlTq1f BIRkGLcy2kmCxcFoha6OfN9yINqS5cX4c1pUNgRCKdxhdWUyew4tB+q7BTkKpEne0g /I/yke6dyV3/BaRy463vISHGnBq6WMxNEN1LebBDqY95JJm/tVmzzADjwZ7OKqJj+m 3lDwfZ3yxZ1HPfsDalMbtN2QAWuW/OKKlf8a5QC6A8bCjKbwcysT7fP56D4v5BsY4i Z5crzK3+pjkyQPrjXIljd7DDG1ZeASYcF7Yt4bRVzqp++6iV+9tjc5LCwjLgGR4khL x7FE03VZRPN9A== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j2k-2g67; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 21/25] docs: kabi: helpers: add documentation for each "enum" value Date: Mon, 19 Jan 2026 17:23:24 +0100 Message-ID: <3b118b157e52d757bf82fd74f03b0f4bd9e8b8f1.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 Ensure that kABI module documentation will describe each debug bit. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/abi/helpers.py | 40 ++++++++++++++++----------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/tools/lib/python/abi/helpers.py b/tools/lib/python/abi/helpers= .py index b8c8dfb1272e..2a378d780d3c 100644 --- a/tools/lib/python/abi/helpers.py +++ b/tools/lib/python/abi/helpers.py @@ -13,28 +13,28 @@ ABI_DIR =3D "Documentation/ABI/" class AbiDebug: """Debug levels""" =20 - WHAT_PARSING =3D 1 - WHAT_OPEN =3D 2 - DUMP_ABI_STRUCTS =3D 4 - UNDEFINED =3D 8 - REGEX =3D 16 - SUBGROUP_MAP =3D 32 - SUBGROUP_DICT =3D 64 - SUBGROUP_SIZE =3D 128 - GRAPH =3D 256 - + WHAT_PARSING =3D 1 #: Enable debug parsing logic. + WHAT_OPEN =3D 2 #: Enable debug messages on file open. + DUMP_ABI_STRUCTS =3D 4 #: Enable debug for ABI parse data. + UNDEFINED =3D 8 #: Enable extra undefined symbol data. + REGEX =3D 16 #: Enable debug for what to regex conversion. + SUBGROUP_MAP =3D 32 #: Enable debug for symbol regex subgroups + SUBGROUP_DICT =3D 64 #: Enable debug for sysfs graph tree variabl= e. + SUBGROUP_SIZE =3D 128 #: Enable debug of search groups. + GRAPH =3D 256 #: Display ref tree graph for undefined symb= ols. =20 +#: Helper messages for each debug variable DEBUG_HELP =3D """ -1 - enable debug parsing logic -2 - enable debug messages on file open -4 - enable debug for ABI parse data -8 - enable extra debug information to identify troubles - with ABI symbols found at the local machine that - weren't found on ABI documentation (used only for - undefined subcommand) -16 - enable debug for what to regex conversion -32 - enable debug for symbol regex subgroups -64 - enable debug for sysfs graph tree variable +1 - enable debug parsing logic +2 - enable debug messages on file open +4 - enable debug for ABI parse data +8 - enable extra debug information to identify troubles + with ABI symbols found at the local machine that + weren't found on ABI documentation (used only for + undefined subcommand) +16 - enable debug for what to regex conversion +32 - enable debug for symbol regex subgroups +64 - enable debug for sysfs graph tree variable 128 - enable debug of search groups 256 - enable displaying refrence tree graphs for undefined symbols. """ --=20 2.52.0 From nobody Sat Feb 7 20:57:57 2026 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 C61762FFFA4; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=tbl9ulyraYUCHMIYTopPJz3/QwX2+A2mrXYfWYQrQDCnXP7uIyf5/cq+PWbK+xvmVMu/SLjtPt8X6+rKAfuV9q6I4VZ992KJOn6ym2M1k3LOXDuQYUTGiropDhnwL2zvcIuJ4ZSMS2tG5OTGohc2e2p+H4cskUh3G+PPAbicAZY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=nryACzQkYVGoIPhbMWi4hHgCP/eXYlXs/XEX5Hcvvo4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=trHIeywqcsjxx0UBK7rK1QJgpueI3bH81Cfe9IOEacUXhEIRiQGHM2273aDBRt02SKnir45JRvYyvOZhZeOh6dEj1vnqJFJWtlOzqwAPoZiaJ9ksE1UwtinBhRyjK9o7K/q6BbHSqcM3+LDnhzmmT49Ez5PG1Css1AgMK/woklw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=fFZjjNyN; 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="fFZjjNyN" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6240FC4AF16; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=nryACzQkYVGoIPhbMWi4hHgCP/eXYlXs/XEX5Hcvvo4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=fFZjjNyNXxM2ofU6YCKansPfY7PQM2PhwxMQ3GK5sWkCZh1jXyyY4DpkOc2hHMyL2 U2p5oHYNV0qq2CbM3khoSMqhMlchIa+Mau6jLPFvPWGPOEYIs9dOAVDrtlU+hUZXXE ZC3hddCKwXC0xOg3PCtwNNZEqH2WOq2GOCGixu1fsoLx10h4C+EfYOZ4DK3Y5S9pU8 ZzJa8nHHVuOPDkJZtAggxJwcc5zbvR2P9mDwbnxX12XV6E7uzAp03afsq0a1G5Pewr DPo64rgVq00GvhsFcr/VyxVg1pd5xakU+2PnujcpZvgHrm8cwYOs4d5QOSU/YIYpKA UMQxd7ylErfbg== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j2o-2muI; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan Subject: [PATCH 22/25] docs: add jobserver module documentation Date: Mon, 19 Jan 2026 17:23:25 +0100 Message-ID: <688215d6a41d78bd5e37854472a5fc802d58c77a.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 Place jobserver module documentation at Linux Kernel docs. Signed-off-by: Mauro Carvalho Chehab --- Documentation/tools/jobserver.rst | 10 ++++++++++ Documentation/tools/python.rst | 1 + 2 files changed, 11 insertions(+) create mode 100644 Documentation/tools/jobserver.rst diff --git a/Documentation/tools/jobserver.rst b/Documentation/tools/jobser= ver.rst new file mode 100644 index 000000000000..31eaf25a8481 --- /dev/null +++ b/Documentation/tools/jobserver.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Job server module +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. automodule:: lib.python.jobserver + :members: + :show-inheritance: + :undoc-members: diff --git a/Documentation/tools/python.rst b/Documentation/tools/python.rst index 978298fba6d3..b196d718e176 100644 --- a/Documentation/tools/python.rst +++ b/Documentation/tools/python.rst @@ -7,5 +7,6 @@ Python libraries .. toctree:: :maxdepth: 4 =20 + jobserver kdoc kabi --=20 2.52.0 From nobody Sat Feb 7 20:57:57 2026 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 C00542FFDF4; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=IKmzSRsZuhETKmICiWz/0qyLfMVd2Fk1qhaRPzYh8tHb++x+sBGjxwRTk8eQCVhTGmHvacXJAksLkrIOFRLIoIJB8OPcLykSIOjVmZWaeeMu4m15OjCEodjurRkyonYQxgq4h0aTzzi0oxttIFy9EpbcyNlK0tTD5x7ASf9OQOY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=h35GQjTzKETww/de+/JJ266keYt1cW4CrK3wQ0G4aa0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=c9jmikhAEJEztej14y5pLm0sPc7Ul6yOzWSzcqpBiiNOm83N3u47qViwyUoc0ybV9s5huc0fWqEoExRV1z7KvbfIpGyF/mYLsJfNRzHRUSVnvU+70tw+j3s1EviLGAgNW0fM/vANfklsBswlyc5dQzO2veTN/VdAh35cvwqeg2k= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=E37Hqwbx; 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="E37Hqwbx" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 62956C4AF17; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=h35GQjTzKETww/de+/JJ266keYt1cW4CrK3wQ0G4aa0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=E37Hqwbxae1udtLLjQm1oGeg1wmu6Fn7z8E/b5/iR2Vt9rfKUIwICBuTNEqb5hAP6 NPcGI9ZIC9ydUZwaPoanNNMfGLaVnfSqMrgcXFCsj1CcC+1YUO5/nGxji9dC8iNnnV lJS1cW51uPFMap1AqGEb0WhH447y92LbYJHzcZhg6I1nt+/LRmGY8g4LkFRYRaRNDx vPUyHlGpb5lTMTh3d/qGuhijAEyfyUvLbRYOquKdsgSoX22it/L+6PKEP9gpTm4hMX FuEUB80nuI3/tCcGqpaIW0OyooxVA7IozPROiMeehx5djny0jrkRVToBcKbHPFSJ1N jNTJKnO2EoyDw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j2s-2ti8; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan Subject: [PATCH 23/25] docs: jobserver: do some documentation improvements Date: Mon, 19 Jan 2026 17:23:26 +0100 Message-ID: <18a9c1406bdead680e3ee5768c97ae8b2138e8ea.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 Make Sphinx handle better jobserver class documentation Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/jobserver.py | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/tools/lib/python/jobserver.py b/tools/lib/python/jobserver.py index 616411087725..8da1973e5c87 100755 --- a/tools/lib/python/jobserver.py +++ b/tools/lib/python/jobserver.py @@ -11,20 +11,23 @@ Interacts with the POSIX jobserver during the Kernel bu= ild time. A "normal" jobserver task, like the one initiated by a make subrocess woul= d do: =20 - open read/write file descriptors to communicate with the job server; - - ask for one slot by calling: + - ask for one slot by calling:: + claim =3D os.read(reader, 1) - - when the job finshes, call: + + - when the job finshes, call:: + os.write(writer, b"+") # os.write(writer, claim) =20 Here, the goal is different: This script aims to get the remaining number of slots available, using all of them to run a command which handle tasks = in parallel. To to that, it has a loop that ends only after there are no slots left. It then increments the number by one, in order to allow a -call equivalent to make -j$((claim+1)), e.g. having a parent make creating +call equivalent to ``make -j$((claim+1))``, e.g. having a parent make crea= ting $claim child to do the actual work. =20 The end goal here is to keep the total number of build tasks under the -limit established by the initial make -j$n_proc call. +limit established by the initial ``make -j$n_proc`` call. =20 See: https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.htm= l#POSIX-Jobserver @@ -40,13 +43,14 @@ class JobserverExec: Claim all slots from make using POSIX Jobserver. =20 The main methods here are: + - open(): reserves all slots; - close(): method returns all used slots back to make; - - run(): executes a command setting PARALLELISM=3D + - run(): executes a command setting PARALLELISM=3D. """ =20 def __init__(self): - """Initialize internal vars""" + """Initialize internal vars.""" self.claim =3D 0 self.jobs =3D b"" self.reader =3D None @@ -54,7 +58,7 @@ class JobserverExec: self.is_open =3D False =20 def open(self): - """Reserve all available slots to be claimed later on""" + """Reserve all available slots to be claimed later on.""" =20 if self.is_open: return @@ -118,7 +122,7 @@ class JobserverExec: self.is_open =3D True =20 def close(self): - """Return all reserved slots to Jobserver""" + """Return all reserved slots to Jobserver.""" =20 if not self.is_open: return --=20 2.52.0 From nobody Sat Feb 7 20:57:57 2026 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 CAF3F3002A5; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=H1cVHmm09t4Akn47Rd6F+4LFBDIWnTYTwjyILjJIr2sS4zngovbEBkb1W8fEomKoi4+hpR3R0hQ5B4PEL/dyDWGV1TllJU9I6fya9i+v78aU/XmgzpvktNqj+IM5lhV07N5cbtkwxc4y3RBfqusLpXEGjIo+1kYGbb3QtjZq788= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=/AtZKw8H6zvX7PhJhNlxPX6rD2v2QCXv+OqXKiT4wpI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ejv2XzxKOnh+50bYvBGFe2lSMT3wtJjzJUBlEB3uyLdlufo6pDla98Wsz4DG5U+/xlXUpD0whDdaO5YTnvhaH/FPXg/5qILJ3uNWhUjMRzXjhnGTL3BeqFEDXoaywNQg/zVrfmq0S3Uy7nbECEYADOmpRxwN5bF5ItyYhE7cSQU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=RSybT2NY; 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="RSybT2NY" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 694E4C2BCC7; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=/AtZKw8H6zvX7PhJhNlxPX6rD2v2QCXv+OqXKiT4wpI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RSybT2NYjYfZDOyq5eigM7E20efea2WnhgLwW4GtdIa6MOOjyDh5XdL8dOVITYqHP puE5nrYRLsMmmsF0tMKyCRkbYMlhBDTRnDhrLVXAas7NmIn6p5j9W54nWAwYlceZjD pl3RecriJrLk34LXlQ71cKaH+dMaw1avzKWYZOasZSOUSNl1Tser4POLpKcnO2v0Fc yMCLwt6XV0Kt3OepsGO2EAcYs8FvujnFDT5mvkrbIwNMQDG8r9rhrDYbOf0ZTpSMTS gaDaDDJEZGnbLalXYIP0jHtFM5krm4cJLMteCg2C4+IV/lzFoPWfcUtFj/ECfrOXfJ kIvqod0AtRxxw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j2w-30TT; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan Subject: [PATCH 24/25] docs: add parse_features module documentation Date: Mon, 19 Jan 2026 17:23:27 +0100 Message-ID: <7c1e41468f765587f0962222e7f52125a039028f.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 Place parse_features module documentation at Linux Kernel docs. Signed-off-by: Mauro Carvalho Chehab --- Documentation/tools/feat.rst | 10 ++++++++++ Documentation/tools/python.rst | 1 + 2 files changed, 11 insertions(+) create mode 100644 Documentation/tools/feat.rst diff --git a/Documentation/tools/feat.rst b/Documentation/tools/feat.rst new file mode 100644 index 000000000000..021560eb6e6a --- /dev/null +++ b/Documentation/tools/feat.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.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=3D=3D=3D=3D=3D +Documentation features parser module +=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=3D=3D=3D=3D=3D + +.. automodule:: lib.python.feat.parse_features + :members: + :show-inheritance: + :undoc-members: diff --git a/Documentation/tools/python.rst b/Documentation/tools/python.rst index b196d718e176..1444c1816735 100644 --- a/Documentation/tools/python.rst +++ b/Documentation/tools/python.rst @@ -8,5 +8,6 @@ Python libraries :maxdepth: 4 =20 jobserver + feat kdoc kabi --=20 2.52.0 From nobody Sat Feb 7 20:57:57 2026 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 E064B30AAAE; Mon, 19 Jan 2026 16:23:34 +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=1768839815; cv=none; b=r/16ppy9sC5b+8XlhoGmmJ+6FmQ9GkFr9c2R1FAScuouxFi2CswTvFSc+9rMWRQ+Pt1ssW15beri9Hb6iIeIWNJSYUpkUVnXTj/c4Yg097UlSfUspeuZFQOWAsJNG1ZsP+bdn/5kKuEDeKL4PS0oLKWZTASfs5MLPfdxrr3HBbQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839815; c=relaxed/simple; bh=KGpR4v2g6e7qWnJ0WpTGEj6sxp/k07RotpfNnId0sdU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=POBYcIiXeptRpMNX03i4De3Rkk78F4ZROxT0DK1UWBhk+tT9Ivb/oiTab7JVj8XKzSOgZbYhT73MyHCJJDqVDN6fN70+7TOUce0I+IbwWkPQ9PCU7e+F1MD9tJTIdw+dk+rzosQcO3ugZ2pPtJPTpeMHOY3j5kJC5hp/7vO4kAg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=e1oBQMaV; 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="e1oBQMaV" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 7D4F8C2BCF6; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=KGpR4v2g6e7qWnJ0WpTGEj6sxp/k07RotpfNnId0sdU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=e1oBQMaVmHSJRQ4YHLaniWoZWdd/nL2tOi6Bewme1B0qL+5NeT2EuLaz7Cshq9k5m J90hvdXHZbNcqaelzpjQPsuCGUMpPwOSv/WRM2/nkwBw/Lscsfqn4Ge6fDbt2++NUY kN3UbW5/OX4b1DT+BU4KDyIwyh7HsiW1cUlHfhgeNSdGXOB+PpuKqfGadi5lawwM41 lpIc4uiKvWRe6jdvPbJCHI+uVOitdBzkrR1EtWdZyFg1dUAZmznkxDmzLNtyfj+aBx 5toqI0k43/iInby3E0vAnj0shpUrVou1XhXe1bpc6v+vgaBB6laAwB8gc2WSqG+E9F iYcA4CNH9PRqw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j30-37Jk; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 25/25] docs: parse_features: make documentation more consistent Date: Mon, 19 Jan 2026 17:23:28 +0100 Message-ID: <3722f10361638561a5ced18cf4f409930c88270b.1768838938.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.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 Do some changes to: - add missing documentation strings to vars; - add a missing docstring; - ensure that phases will end with a period. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/feat/parse_features.py | 27 ++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/tools/lib/python/feat/parse_features.py b/tools/lib/python/fea= t/parse_features.py index b88c04d3e2fe..41a51d9d6f62 100755 --- a/tools/lib/python/feat/parse_features.py +++ b/tools/lib/python/feat/parse_features.py @@ -21,14 +21,25 @@ class ParseFeature: from it. """ =20 + #: feature header string. h_name =3D "Feature" + + #: Kernel config header string. h_kconfig =3D "Kconfig" + + #: description header string. h_description =3D "Description" + + #: subsystem header string. h_subsys =3D "Subsystem" + + #: status header string. h_status =3D "Status" + + #: architecture header string. h_arch =3D "Architecture" =20 - # Sort order for status. Others will be mapped at the end. + #: Sort order for status. Others will be mapped at the end. status_map =3D { "ok": 0, "TODO": 1, @@ -40,7 +51,7 @@ class ParseFeature: =20 def __init__(self, prefix, debug=3D0, enable_fname=3DFalse): """ - Sets internal variables + Sets internal variables. """ =20 self.prefix =3D prefix @@ -63,11 +74,13 @@ class ParseFeature: self.msg =3D "" =20 def emit(self, msg=3D"", end=3D"\n"): + """Helper function to append a new message for feature output.""" + self.msg +=3D msg + end =20 def parse_error(self, fname, ln, msg, data=3DNone): """ - Displays an error message, printing file name and line + Displays an error message, printing file name and line. """ =20 if ln: @@ -82,7 +95,7 @@ class ParseFeature: print("", file=3Dsys.stderr) =20 def parse_feat_file(self, fname): - """Parses a single arch-support.txt feature file""" + """Parses a single arch-support.txt feature file.""" =20 if os.path.isdir(fname): return @@ -204,7 +217,7 @@ class ParseFeature: self.max_size_arch_with_header =3D self.max_size_arch + len(self.h= _arch) =20 def parse(self): - """Parses all arch-support.txt feature files inside self.prefix""" + """Parses all arch-support.txt feature files inside self.prefix.""" =20 path =3D os.path.expanduser(self.prefix) =20 @@ -281,7 +294,7 @@ class ParseFeature: =20 def output_feature(self, feat): """ - Output a feature on all architectures + Output a feature on all architectures. """ =20 title =3D f"Feature {feat}" @@ -331,7 +344,7 @@ class ParseFeature: =20 def matrix_lines(self, desc_size, max_size_status, header): """ - Helper function to split element tables at the output matrix + Helper function to split element tables at the output matrix. """ =20 if header: --=20 2.52.0