From nobody Sat Feb 7 17:55:12 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 B464A395DA9; Wed, 14 Jan 2026 13:17:32 +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=1768396652; cv=none; b=fEA6gCd89p1tSSRr6wbh+ABKMzGciWUAmkLciaLjPovtc3uLEAzkRfSAAvGUpqeJFsRFDIbXuLi3V0b+9r8itgliHC7Nc9DNvP2RwA+Ed2t5dTP8ujqURZOxHUw8ee8qq85szm25xN2Gxjh1iJhUQ7j/cu+RoTN7giYqJZ6gA5Y= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768396652; c=relaxed/simple; bh=exjBpROHq5nt6ys/3V4S6O/quh/Jy14gJjvOKZLMHAo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=P9HHFLfJ/UFfIyUN7loa9+Pdfd8WIXyo4Rr2XdsLUNx1WCb6eIAwLEOX8J3wuXVzdSdhXkRwB32FC+EYYmZVA+NyQ1grQgg4Y5EPMEkwKJNM/ynNFkgaB48gw+U10DKouckSTVlxbUMZpqIphNDga+FIc3k/awPqhpXmSPfOovU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Lysnj4L8; 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="Lysnj4L8" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6E4FEC19422; Wed, 14 Jan 2026 13:17:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768396652; bh=exjBpROHq5nt6ys/3V4S6O/quh/Jy14gJjvOKZLMHAo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Lysnj4L8lUZvSwqK60AHspBOkTZk+2/TeppDAaS1mLPdQhzT0iTKtJOKsLB3hEqYs 23LR77WTMpKMuuiR2ngmoDinnXD4gMwp2B5+/EQpG4rRGQ8ojc5Mv8UNkPQMkv75iK CZgqq3xStmN7bJPeplMUxYHcxBRdKUyC/FaspSj/dP56MrXyKCRl2YKq7LIFo6RYw2 e77DtU2x3zvqCE+6POxIXvFuup2e6EEzEi8JumkH6jig+5FSKcG1ofQ/BaPRKrLBgg MW4Ko7QzSmmvB9TBrvTcAZ0t9i37GE31njh5hS8z7oTGR2+7sfQwYzc1uD3JIHmFZ/ IOQjdlDPFSPhQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vg0kc-00000002mxY-2wEi; Wed, 14 Jan 2026 14:17:30 +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 , Shuah Khan Subject: [PATCH 01/13] docs: custom.css: prevent li marker to override text Date: Wed, 14 Jan 2026 14:17:14 +0100 Message-ID: <8a6e0e40f45a6e92e18c20f6c98f496ab5beaeef.1768396023.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 06cedbae095c..b6a7a5f6b6d4 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 17:55:12 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 B45C038A70D; Wed, 14 Jan 2026 13:17:32 +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=1768396652; cv=none; b=RSHjcYxUu2hKGnzFj8v3DHJsToMVMnv9XPgO7+KKrJGjTqN9Eu3ZklgFRPDros5H/n+PxTJBz+CNt6SP2ZWJvLzZadIFccPRM6y9aQf5H1wPweYfOszkw2oQONRx8v+tevzI7fgrRrFaKy7s4eibYqkup9BT5UFVMJKAMgsXPws= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768396652; c=relaxed/simple; bh=/ChTPMTJWguRRKmJf9yWMTMAI3kBzNamShtWjsKKzK8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=sRmLkBATKLx/78r8QFeTzmrGpr4ovP1t9ZcDOhHCk1daES5oACxlZqMe9ZCcXwFjc2JORh+mKjEoJ9kv/XoY7NAfGFNKSEBnE9x62EhoXf8DW4jEarjCDiTfORxiAWeMdxrZ0JK2FiDoYTG7zXZqaUpXh5Ig6prbCmyUSZXdJrc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=W0mWXyYy; 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="W0mWXyYy" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6B199C4CEF7; Wed, 14 Jan 2026 13:17:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768396652; bh=/ChTPMTJWguRRKmJf9yWMTMAI3kBzNamShtWjsKKzK8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=W0mWXyYylmF9Xe+hgWcLLha5QQdff4rTPSA+fV1xfBvz6p3fTDozwo9vfHyXmWHsF Fs9+ll1kSlgyrv8nFjILCDwf/ehOQzXddTdEBQcCnugQHSkgNZecMsMolIk6TnG/pn xN1w8h35iYsej9N+NExloaYJ4/itoPqozOUFp2yvAVr1BCLlxkuamkSqWleDFRbj2p gCtTXqCO3QmI3cF46QQnKwBTriXTR5zexdgOOVYV7IpiORRhz266ssI3cJ4q8p2IhT wpxO8vLPoLh1qS8BTg1NzwzZSS6W9P0kUkfEt0XY87LSU+HRU/ge2XE4OABZr4iTvp GJ1cGy+4vkqeA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vg0kc-00000002mxc-3392; Wed, 14 Jan 2026 14:17:30 +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 02/13] docs: enable Sphinx autodoc extension to allow documenting python Date: Wed, 14 Jan 2026 14:17:15 +0100 Message-ID: <6aa5a5b4a686f07c8f3e6cb04fe4c07ed9c1d071.1768396023.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 | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 1ea2ae5c6276..429fcc9fd7f7 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -13,11 +13,18 @@ from textwrap import dedent =20 import sphinx =20 +# Location of Documentation/ directory +doctree =3D os.path.abspath(".") + # 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")) =20 +# Allow sphinx.ext.autodoc to document from tools and scripts +sys.path.append(f"{doctree}/../tools") +sys.path.append(f"{doctree}/../scripts") + # Minimal supported version needs_sphinx =3D "3.4.3" =20 @@ -32,9 +39,6 @@ else: # Include patterns that don't contain directory names, in glob format include_patterns =3D ["**.rst"] =20 -# Location of Documentation/ directory -doctree =3D os.path.abspath(".") - # Exclude of patterns that don't contain directory names, in glob format. exclude_patterns =3D [] =20 @@ -151,6 +155,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 17:55:12 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 925202F1FC7; Wed, 14 Jan 2026 13:17:32 +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=1768396652; cv=none; b=n9MQ4kyhQFZfbc+SLjW7lQocu/gEYHs3gLn9VMTn/QQe2w1WB81w410hdIYPBJT+L8gPN0H6Hpc7BpNM3XUXVZ2kAMOZF8Y6rzdBeTIN6wfju1HUnV/57dYKb2YSs+4YfgMTeW8ixmowYNKVnFsGtMUD68baFZF/4aC51RrLMHM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768396652; c=relaxed/simple; bh=wfHr9wNKFyYIJ5Okyj5woYiW9cOVx06PeOms6PzwjSI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=l128fFWYD6XW2nLp5tz2vFDlSVoDElZQ1aqIx2BTpdtoBQeP3/7uZtt2uVtTRGk9lZ1kNFUcsuOJrFQBuVdLW/DiT3VkxDj9TZmylfTbqO3FyfKhbYEgfjpq4I/xQ9xxxJUlYOODVApO/ZsCGIfgxkGI2X58NzGgG3ply4O98Jw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Eu217KBb; 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="Eu217KBb" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 74BDFC19423; Wed, 14 Jan 2026 13:17:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768396652; bh=wfHr9wNKFyYIJ5Okyj5woYiW9cOVx06PeOms6PzwjSI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Eu217KBbR/wsdAH7oSRVpqJz7AkvudzUzCXdVxwp+c6u6cPvE14CN8FNSzNXWvXWm IUmN8wUmaD+fRZkv7nTb6cm6q9jm3p2cJN3IydnMWMS0I4i4XAH0NilGP4HtL7wMMC HNEMJZo9jrfzOVA83EqPo/UvK5HJ31K9AZ0RLWpFemf3XDtmXkxPuoOo0ogE7WQ/u5 v++T/86HQFqUoqG7QWo2Dt5lV4ZEnVmAGaJpf9KtjjV21LQoRJJmRRRgBfdAHCknTJ +rgbjjRiHSF8Qr/0ibNVbncbiX2gPMiivyCoyR4XnJraujnXYJU4pcRI2NyBRcZXw2 jddZYoLJ5MSgg== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vg0kc-00000002mxg-39pF; Wed, 14 Jan 2026 14:17:30 +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 , Shuah Khan Subject: [PATCH 03/13] docs: custom.css: add CSS for python Date: Wed, 14 Jan 2026 14:17:16 +0100 Message-ID: <8d66988f05d06d10938e062ed4465bf303c51441.1768396023.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 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 b6a7a5f6b6d4..794ed2ac8a48 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 17:55:12 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 BB22939B4A8; Wed, 14 Jan 2026 13:17:32 +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=1768396652; cv=none; b=usMA389xmkuHBDitEUg2MpbxhmTNrjLlr+nz907g9HCvCGraSv4SCUvHTliEbcK6AAmqtIcWTfChFcsJGUyDaHqNNb+c6+Xx5tiMGr24Z1x7Kul43RFoo+xTb6BC3u2MkZgA6RHeYezc8tq26Aw2kHhsfHo8GG5xOoyefS5dNxs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768396652; 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=SB00hB9STX20YBxaLY5yA5iUVNF9VymqdcunBogDo1LzI1CVxVBjgdd0H5SJfsvyYI7P7KbypbA07RAzoDD2f4Mm8Dyl+VuBlac+TpMGwdsd97KAKG8T78XRzFWOa3P4NzBBEmx7h1UtEB6JCHAxi1cPIkGnceAGXxMvu4Q1SZg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=kWes6Urx; 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="kWes6Urx" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 83C6AC2BC86; Wed, 14 Jan 2026 13:17:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768396652; bh=V/BLZs4Nlt58GEgPnSOwtNktnB67g/V/fdysHWNMdM0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=kWes6UrxbEbLekLy9Vnnt956jh9ZzAyjJCcL5x7uun5boe5iBXXeYXFTaUFo1noXq qcHrrmy7/qWY9CRyaFfHv5C9gEgo+MtGBDi5CXL2c10aICi+1ZlJAyENiujFhWfUSq Y7ZLw+V3ER0Bhx/z/aJYQ0pX/RoJikEyrtD5p3pKiO4fI+PcFgp5HgVM8wcakk5e3O zlk6G9+e9TYQuyBWAwW9fIeSnqf8aHyt8XdW2syzpM03tMiCbSnOa8kKqpXC1pbvev hTxdIfa4SsKbinlitq29fSospcgNn5v2bHffJ9uW6UBZtDMZujiP+7kbflRz+fShNU ykse6EazSetwA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vg0kc-00000002mxk-3GSm; Wed, 14 Jan 2026 14:17:30 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Mauro Carvalho Chehab Subject: [PATCH 04/13] docs: kdoc: latex_fonts: Improve docstrings and comments Date: Wed, 14 Jan 2026 14:17:17 +0100 Message-ID: <646e3a478f1838a951b05df176a107e2f4ebfcab.1768396023.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 17:55:12 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 BB2D739B4AA; Wed, 14 Jan 2026 13:17:32 +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=1768396652; cv=none; b=kct8F4FxJoMZup7Y4QNXKmPE6l8EJhvnshLBlCZfq5odFUJeYvCMvO82wUuw+0fB4oxcHemKJvZdhY8651n9m96YjdtD8FcfTjBsMVxhMVZtyjEdJVvLw9Ivzv48RsJTT6EQ02rboOHy4sxEDOLTrEhxPMINT3uoElrMLCd1F8g= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768396652; c=relaxed/simple; bh=D20byBH6Dc3S8kqec0afWoBETHqoICKqefEL4fRTSCc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=thJZwZelkMi0jtqk4n9afYIskom35UqMAqV/wYWrO4D/ROv9NAOGjhJ5mKfXEB+eDSVxC02XHDT9W0mvIq1VfyDQUzVKLQKzqYMyzhpqkOSnQ1iTcf9ArxfdKKuN+OJPIrl+GQSRRhzWlgVudRMml0Xm73veeUHS5lFOlu1W+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=QG8LpUQX; 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="QG8LpUQX" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 826C3C19425; Wed, 14 Jan 2026 13:17:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768396652; bh=D20byBH6Dc3S8kqec0afWoBETHqoICKqefEL4fRTSCc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=QG8LpUQXloJmXI6yPwA76dzJm1UgLxlZ9fxT3JehKor7f/rbOOPjkh0ZxmGSFJMVH eNZmHH4P5H21+1w1/7+omL4TtBYHmY7XuVjaHlEor1VYUlNF44wR7Jawd912m0BoGf +ODnKzxyaxec2gme0N3vHn/zlPoP3uSyadSi8yGrSSNoSoJm0iGvgrjHcvzQAvyDc5 iPXmWKi3sOsytgCBQLNvYXWw8m1rcu5uvhTYek9TQw+gM0AaJ7q/Pb1Fsy8K13Jji6 20+6CbNubwB6CoQfZ4vGaXXeAfdI7dmOKV9pqzOD5KyCIY3pbXAqR06HnS0xcazmwA odoaDQyBIoaGw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vg0kc-00000002mxo-3N5c; Wed, 14 Jan 2026 14:17:30 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH 05/13] docs: kdoc_files: Improve docstrings and comments Date: Wed, 14 Jan 2026 14:17:18 +0100 Message-ID: <5bb81566bdf632344c59e1ea4a9283d0aa5ef20f.1768396023.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 17:55:12 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 C0B3739B4AC; Wed, 14 Jan 2026 13:17:32 +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=1768396652; cv=none; b=DWdwkr79nOl5DWcAiClS8WfagZ/RnGd6y9cHoCR7wXH4EA8976FlmXsv0ixkTBjslwK0068IFJKRqD9R6rfp1eHq0e2CXFkOpyb5HT8RpRtbiPt9BdiW5RaW5CHFv3XD/L5qjW/0+n6SxgsbU/t3nk+k0ei5nZVZ6O5oCZL/CZM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768396652; c=relaxed/simple; bh=kmk1GvA8qQBm6LrMB53lcAYigASy9DuUwFJjdBAuCYA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=H6pMDdpWdwaVhUoMSrs4/TgrVfr4YQ9ZijZ33ZjEmhe+rqA+xgvj+rpAA/8eDL2SRpgeiHeitSt3vEFVlabAg4K3eckvJwYsklVy7l6ZbtfKOOdw+ScTSDuJSEqab6Nah62BjsyvBUtX0Daszlge321pgNSSSI4KPaRptpYMDn0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=A1Qae+5k; 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="A1Qae+5k" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 923E9C2BCB3; Wed, 14 Jan 2026 13:17:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768396652; bh=kmk1GvA8qQBm6LrMB53lcAYigASy9DuUwFJjdBAuCYA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=A1Qae+5kagWskVqy9Jf63IY27hG6XPXtll2q3XoMsUoRLbqevfIaIbAC1W84fqAYc ZdkZyrMwKDQqz3unUakl3I7HOTZUiNW5osgkM2rIug/Zr6aRbq3d7LJl2vZLkYvttO giVVrg8ktCAbjrIejkpF9qOyVHjOrFF/1M5mxe1hOktoMi0PO7UBitaLmfzwV0VoaK Gm1h9+1NFixYnJiBkPt8gbFUuPDvuqF8H+/g2lg1THJGFlREKXksFepIrKFg9Mhs77 2sviVB8zuRed9W2u4eHrq3P+lnrgKhTo12qieakYMR1Bf2Fyn9KDPQDoFIoX8YzCIr 5CbUvOj069bhQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vg0kc-00000002mxs-3TsK; Wed, 14 Jan 2026 14:17:30 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Mauro Carvalho Chehab Subject: [PATCH 06/13] docs: kdoc_item: Improve docstrings and comments Date: Wed, 14 Jan 2026 14:17:19 +0100 Message-ID: <11886c558d094e382acb415bf834fa4da05053ad.1768396023.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 17:55:12 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 2CA8239C63A; Wed, 14 Jan 2026 13:17:33 +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=1768396653; cv=none; b=RmT8iku6ld+W0QKVuMKBSLJiLzFtr3spTGfVZDq/ARZpc/F4a+zKWb5BkUHkoc18gWKk1dyad52jeY4xvWUTt8WEOxXeCJL6TODbbZ3Xt00p09kGOpsrsDq0wdLkzHplC6C937uaHLRToa01GngDH7vPidq9ptrT9S4qTB/kW3k= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768396653; c=relaxed/simple; bh=PjcXX+7VF4mUhL09sKoUs37UXwFoFKowe+ZEsFz/zRs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=oab1cClwDfBYlq2V2iCPiJzTH2dFZQag5KwoysC3R1NPXIEZSjJTkE49ql7t2msmoQqsXF017hFSCWwETLzrSwJZYhi2u3zYMuqLGLMlFigtL+T5A2CchT7orEKbyTMGp78zBDbQRggMu6YxdvjZLedVsR2ZCpYmhlqnK2oX7LM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=d49fDsPy; 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="d49fDsPy" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8CD3CC4AF09; Wed, 14 Jan 2026 13:17:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768396652; bh=PjcXX+7VF4mUhL09sKoUs37UXwFoFKowe+ZEsFz/zRs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=d49fDsPy+bMTT4WNVm6gxOdmAXvAZJ4MT3+xTZ3Bu02EFZhdTWgfW+Kj2ataHGnlN 0rn/TXH3ozN5B7b+KbhoK3WrKGF6A88liqQZZK8QeYgFRIiyuHNLj9bPdt1EBdz00k +4aU/PQLQxO+Vm9CZJ3gItDCR5BJ8G0qq1hMMN6Et2q+agkOecUBBC7+2rqeELunqT e2LYx2wDSgUbYahoNtpGE9RaSVgLn1rujKlJe7s0T7EcJt34C2c1dmF0H17A4eD0Qc YIDRzP6qH0YPnWFL06bLRyzCZnyzqBIxK8PoTA1HJZpj7+swC0bQ1+ErcRQsIHPnFv lK78dMOLh13Dw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vg0kc-00000002mxw-3aet; Wed, 14 Jan 2026 14:17:30 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Mauro Carvalho Chehab Subject: [PATCH 07/13] docs: kdoc_parser: Improve docstrings and comments Date: Wed, 14 Jan 2026 14:17: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 In preparation to document kernel-doc module, improve its documentation. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_parser.py | 175 +++++++++++++++------------ 1 file changed, 96 insertions(+), 79 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 4ad7ce0b243e..fd57944ae907 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,14 +292,16 @@ 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 def emit_msg(self, ln, msg, *, warning=3DTrue): - """Emit a message""" + """Emit a message.""" =20 log_msg =3D f"{self.fname}:{ln} {msg}" =20 @@ -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, @@ -456,7 +464,9 @@ class KernelDoc: =20 Ensure that those warnings are not lost. =20 - NOTE: Because we are calling `config.warning()` here, those + .. note:: + + Because we are calling `config.warning()` here, those warnings are not filtered by the `-W` parameters: they will = all be produced even when `-Wreturn`, `-Wshort-desc`, and/or `-Wcontents-before-sections` are used. @@ -680,10 +690,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__", @@ -702,21 +714,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 @@ -794,11 +811,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. # @@ -832,7 +850,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. @@ -874,7 +892,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 @@ -1021,7 +1039,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": @@ -1038,7 +1056,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 @@ -1139,7 +1157,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. @@ -1193,7 +1211,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. @@ -1224,7 +1242,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): @@ -1314,10 +1332,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 # @@ -1349,10 +1367,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 @@ -1371,7 +1389,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 @@ -1400,7 +1418,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 @@ -1490,7 +1508,7 @@ class KernelDoc: =20 def syscall_munge(self, ln, proto): # pylint: disable=3DW0613 """ - Handle syscall definitions + Handle syscall definitions. """ =20 is_void =3D False @@ -1529,7 +1547,7 @@ class KernelDoc: =20 def tracepoint_munge(self, ln, proto): """ - Handle tracepoint definitions + Handle tracepoint definitions. """ =20 tracepointname =3D None @@ -1565,7 +1583,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) @@ -1610,7 +1628,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() @@ -1664,7 +1684,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() @@ -1676,7 +1696,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() @@ -1693,10 +1713,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 17:55:12 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 D9BEA39B4B8; Wed, 14 Jan 2026 13:17:32 +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=1768396652; cv=none; b=OTpOsmoe5QXfnywEjkZrOO44HOK+VApmWSX6ai2sizSl+1mW4Uj4FZUngbUN/tuN7wcnSZOX0XkT5WoIfVmGsF7EUsRx8wTMKpmaYnaxSP85PwBWuLRbYLJ384ZgjU2US43zUNgXjyPXFue/8vZa/SyAAh2KNyZc9uPpHsdwMv8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768396652; 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=oU4hzxR66rjUlKF+TqaO08mpZV43uscHmQ7DGGQfiN6TsCb5b8q7hzKor0DhPRCVariiCSEwEoSaGTH0nY0QEbruL0q114UbLV4TENXGVFweHqRV2M+RAdXCk4fZwGifW2sOtvX3fb+9Ws7OWIRxuuud056TKmh8M3sGAKabP90= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=RaEmenRi; 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="RaEmenRi" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9FE01C4AF0B; Wed, 14 Jan 2026 13:17:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768396652; bh=FI+Dh9Iu2wtKz8NU+WdlvdtlEUg2nNsIV9O2y+kNbi8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RaEmenRiqRiN5RDw7J9rKnkvjSK41QYQPQXNO6sN0ipLgUTRtmMvt8c3TbA3S5FNd ZSoWsSPr/M/TDlTD6FVDeAeQNtyA6m8ZXt5gIzN59bie5GqRloFWIRTVjjFMUq2m7x Fw/u0tn0XTr2lxJrvPs+AhRhriQt99wYfTyPVo0r7MI4yxbfYCnSaO5+FmAeF/E4fk GtfesHjy3hplVQppJ+eQqwKtH4eF5HKNKS/uQfQ3xJgwLrrP6Np++zzYwjyviO40gB k90jn01vsW7S8choSEopJC8oOx4YI0qOkcq4ATVKFTKlA77dRvRLYZ2QbLHVbD7PHa av84NWtlheOyA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vg0kc-00000002my0-3hJO; Wed, 14 Jan 2026 14:17:30 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH 08/13] docs: kdoc_output: Improve docstrings and comments Date: Wed, 14 Jan 2026 14:17:21 +0100 Message-ID: <45ef9017d7385a86c0048c5a4e66bd39a1a099b1.1768396023.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_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 17:55:12 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 D9B1E39B4B7; Wed, 14 Jan 2026 13:17:32 +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=1768396652; cv=none; b=sk+QjAV1pzQcM+CFT+SZZZUQkvGqnhgK4o0rcjfTnvL3QRQm2lBc3zEYysBQis0MQ/Rh3owNFSUdbmAI9GqLsvNpUyecLFDiC3w3fhyqX0Xvg2/AYjDfIu2mYGy0YqYS59ymCFmUEsLSPNcd7X74JR0ToH+YfH9xKoVedTOvdqU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768396652; c=relaxed/simple; bh=AT9QRc72PaX75+hy9TLUQhCbT/HxXyi982eiR6wBTwU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=XNssTRc6rC3RJCwQXzwU97TpjdVAxtXDwTAO5FUhBQL5r3abkP7zPRm9sge0AwRo3OuNOde/xlCe87dv44wyJy56QovbA1r+qrOy86v0RcfH+yt17SRztiCJsJCOXAsTlhMdOG+tm6+Grfbv7Z2WQLIg5uflfqkWlUMgDgP4YU4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=dZVLD9D4; 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="dZVLD9D4" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A0590C2BCB7; Wed, 14 Jan 2026 13:17:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768396652; bh=AT9QRc72PaX75+hy9TLUQhCbT/HxXyi982eiR6wBTwU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=dZVLD9D4yv64QmkwAgRHO5t2AVwIAP0rrzKjkQyHVpjn+ZfwNmsQBSm1pnr68nMaJ iKAO2zyDRPRGGpifS1RPLJCw8WpSfX6gSk2VYJ/nrtoTo2XblZf9GDx33Wy2qC5TOy Rs6i6NRxQFkZKc45eMJ+KVepaBtXZk9MPfdaxTopFrMlD1lhkisP3xFO94TsNLj0Lj yPyjZrx14ScLHSLSKV+FMSC0KArVGC85B7SupkgB0PDeAvlzTrwAI+n7yAhpIZdsPI 35RLFUYd5i4qD8rMVXeVH5DvVSbpDKzxTP+h+hLPcb3BpwmdP+qMxi7LmdniNwO9Uu kuwSJBwyQS8ow== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vg0kc-00000002my4-3njU; Wed, 14 Jan 2026 14:17:30 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH 09/13] docs: kdoc_re: Improve docstrings and comments Date: Wed, 14 Jan 2026 14:17: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 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 17:55:12 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 DEB9439B4BB; Wed, 14 Jan 2026 13:17:32 +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=1768396653; cv=none; b=cS0gE5EDu4ApbMDzy5poDm+6q2HFwVMRBl64KQKQhZC52JD/c1BxxB9OZA0ZeEtklwtRejUWF8TGETuIIsFM9qoZwCV78Ypzr+vQzW2g5TRIqrsTRggCtRG+acYF5/vTqGyFAg79SnprguZrRycbXgcumhLWqpaXfemmuoeH6bM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768396653; c=relaxed/simple; bh=i1tcZCaxJM2MU0fiO/S47vsflPzYkddGYteNjd18qHw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=qw+AD+WaUd1jnWKVQp/7zQDwmffdBtv9wvon/ijxUZgFe6BGDuUzpD90HWV+/eg6jUtvu9QyVIro7sK7ZBpPqokIXFQw7PWkJZcNGRiU/xOJxjPLuMG6Tr/xCdPHbQk0Xa5ldqgn8iYOCi6PvshuNy2fAJ0SFCbsYB8PRWBcMeo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=syU5rtB8; 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="syU5rtB8" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A6621C2BCB9; Wed, 14 Jan 2026 13:17:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768396652; bh=i1tcZCaxJM2MU0fiO/S47vsflPzYkddGYteNjd18qHw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=syU5rtB81qR3By4ZnK1duSMAv8xu0ZSMNWeaSRkKmG8bTfYZRA+Dvd9CoiRBhoWNj OFhjF4bSFWL+EDA4Hs7wggAoVX6Rvy4mnFvlHGuSs9uuC0TfVY0iUl5LO8iEdsZSco CuiwH1DPlabZlnF1EdtBuKtDsFEuMpMkjZ/BrmUlBwIpBc4xvhzXyVydiPEZjwa34O Wy3Kw7hti7PdRaATTWFg2YBPk29vFr0g/1XeqFM0ZstW/ACRgkKDaAz1VOKj7wvOpB Mb9En3YL26HMUfxyaMuC0ya7Rltn5iFLmmrC4GUrXg9TWO2ZjRVrDhL2e/ho9A2wzq h4w0ij4g2Wo0w== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vg0kc-00000002my8-3uBo; Wed, 14 Jan 2026 14:17:30 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Mauro Carvalho Chehab Subject: [PATCH 10/13] docs: kdoc: parse_data_structs: Improve docstrings and comments Date: Wed, 14 Jan 2026 14:17:23 +0100 Message-ID: <6e009233720c331d51e0f6bbbf332410dd8f6da2.1768396023.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 17:55:12 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 E1C6839B4BC; Wed, 14 Jan 2026 13:17:32 +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=1768396653; cv=none; b=s93t+8We5paalby4C3VcZVSxsPLDEJXe153m3LhV33usXaeJOw7Deq6XL/YwPiSinVUWd+nAtwC0E4dN4i2/XBXfr9G3g6Jw+Urh/vAoEnXSHQxs66rhPfoRllu/eHNUJ2LD6s9afNIXoXTrfPm1isTRhB/SZqqWK/KhoPL8QAc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768396653; c=relaxed/simple; bh=EJEpOIpo13K5wVlZXAiPofrL9GMVio3Ohn/l0ADAKD4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=g6COkmryQvZVLBsFgl9wQd4Iye4LMuTuM1+44I1FPo4DxEWu5b6rblDoQ/V1DUUo/XHAWkyfPV28AeXRgyjLUyVb6O2jXBFJ+5+knjYc4gH+rHv3ge0t9k59200z2KFlJnM1GZ9icuM74RN5YzfUfCoZ1NwSgI/5c3XrzksQNfo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=DLbhrGZ+; 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="DLbhrGZ+" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A96A4C2BCC6; Wed, 14 Jan 2026 13:17:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768396652; bh=EJEpOIpo13K5wVlZXAiPofrL9GMVio3Ohn/l0ADAKD4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=DLbhrGZ+0j3jD3BMgsfu/nIsI07kioZVWxH27YQqN+s8CkQ6L3Jf2aVPKadfDF/WA 6xNAKoNi1PRVZVKQvrHeobonhOPEpNxwF1RG5UNDO8sGuSux0vhmxoB8TWU6ETIPd4 /nA2Igv6Vx6pg8AMmSseOvwyIVvUVBh8EgPrHcdcSmscTZlekNwtcolYeQCjYrYj6I 43KnpFHuDwMjk9WB+OZ9B8flPhmFgt1afKK2bXWl8S8KDwJ+L07C6ObJwJoo58Z6Cl bR0FI8MbkrDt68PY88J05yzQ/WHU4vi4/ni4K/wK4/J2zEn7HhrWRexXnq4BmP0AE5 iLhXGFeC+IhMQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vg0kc-00000002myC-40fC; Wed, 14 Jan 2026 14:17:30 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Mauro Carvalho Chehab Subject: [PATCH 11/13] docs: kdoc: enrich_formatter: Improve docstrings and comments Date: Wed, 14 Jan 2026 14:17:24 +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/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 17:55:12 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 E581639B4BD; Wed, 14 Jan 2026 13:17:32 +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=1768396653; cv=none; b=rpKnENtIL6wfbbcIAqK9w9Lprmj5amqqgY37SXuqeFpQrqrC6WnRiHVFzvNKbHXieeSC5kO2Z7RJK3gM3xiI3lqvNLZchEanYmvIt+GPfXN01XNyML+YzBKYbElS6cNkxmSQcPjnWmFXYMJBmVgL/QlL0Nb+FppCfQW6Uo4ctwI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768396653; c=relaxed/simple; bh=qeD2CxushaNmzGduOrZz2GnZPSRsopACODszEDevkew=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=HrPWAXu78/s4Lqv0WEsHpaQANa1PNlTsHVeiFCZGrrDHJ+DX48Yi1fXXv0ac3TNO9Aimlb6aUSrOukdSijDHR0pjh3A/YeP/nByW11BYnffDev/iQU7z6k81j0qmkE3pFr7iJopFrh/N/ZULv6fLSy5Q6USAbHknwQZSOKmqVKY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=nxRyHydP; 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="nxRyHydP" Received: by smtp.kernel.org (Postfix) with ESMTPSA id ABBE5C4AF0C; Wed, 14 Jan 2026 13:17:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768396652; bh=qeD2CxushaNmzGduOrZz2GnZPSRsopACODszEDevkew=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nxRyHydPtCXWNMVn+k9Nv4QXcZEY+FngSC6plZr4STdEr8EuDSZrLxYSLBM2uFGhw 9yT2HkeUcxkQlMrGIXfvA7/Ubx3y2WK3myulNYcYtH0Y36/Qu49PKXp+FlewEcTCUC qygjlFQilUM+Mtc2oulnPCKc42p5UUji45xoEo3diz8aLDOgyeada/wq4ahEtRoOld XVrtH/M9ndjcBEj2LUj5YOrvcvElcxdX+0s2qILS8OLdi9Mo78I0zCBEFupC1Vo8bm lVtiouHD/2JqWa5Vq3rMQcD0vDOue0XKM1J92Q+8r9qLMtcRE3PA4gHhk/N9VoV/Sv MNu20iSUHPonQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vg0kc-00000002myG-475X; Wed, 14 Jan 2026 14:17:30 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH 12/13] docs: kdoc: python_version: Improve docstrings and comments Date: Wed, 14 Jan 2026 14:17:25 +0100 Message-ID: <340032ca56db393a2a10dd828bedf5e63c7983ca.1768396023.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 17:55:12 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 EFA9639C621; Wed, 14 Jan 2026 13:17:32 +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=1768396653; cv=none; b=TnCya1M2v0AFbIoJ/oad+3KxCDEu6ZQpFIhwUBKRtfrzNiEsL5/gAp5otFPSrbPeRm+hxRg44pCi/InB75/0j8EVe530amWLYsaa2twxu2WDRHI7Ph6gcxb5KO5dzUqIwmTdxT/kgNh/A2DUr24SaDCzJ6BEvpYH+UZE+oOR0C0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768396653; c=relaxed/simple; bh=s1mjnTzuhsFarODXcVZv6x/pyTkp3qp8CK9/urSRqTw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Z/R3yIy30EbG2tZ71M66wLzvSA24jY8HnFSWuXZcvXcoqGZwtYjPeLq/WDYPIgPr9rvbrIlBKEJlOAJnM9/+j8SkM3QahngYYifNIhO03FhT2u7M6jvSI3RQdm4vmcyCTEaSFIMqQtZp5MF/qJ5teiX/fRj8sGyGDV3ay0WFAFA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=K539fdIo; 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="K539fdIo" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B3776C2BCC4; Wed, 14 Jan 2026 13:17:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768396652; bh=s1mjnTzuhsFarODXcVZv6x/pyTkp3qp8CK9/urSRqTw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=K539fdIoltpS8MpyRvr1shx6RFNu3ILQcG0NcCi9SHSh9VzLqag+IHVlTDJHJb35J yZ1A4Kvugydu+/z9rYwocogz7FwhSNZ6JLurD2nKjH+4rwTTPOMX0x5IqInRLiDujC hR22cX26fl6LS0/aBawoFddzcMfIEh8vu6CAy7+sbpqBPoYznm7U0PE4tIAKaR8wIe L7sIy1iPbZoJGfqSbJxHw9h0YZ/EPQ7/VCVj/M20Jxeavs31SKOAqqtJnJTNSQBl5q 00SxDkPTpqC5ygwCLjLmjZpZs6dSszSmDF3uAiGVn2FD+wi8snGBYlwe7rzNhIm+5s /hHkllzB+3lAA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vg0kd-00000002myK-01Ze; Wed, 14 Jan 2026 14:17:31 +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 13/13] docs: add kernel-doc modules documentation Date: Wed, 14 Jan 2026 14:17:26 +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-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