From nobody Sat Feb 7 17:55:13 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 51FC036D4F5; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=RRL8IWa14/7VPbAsIoQdD0e+lS+Lrb2zqhCeIN9GanyqFaUF+jZRGhY8ObONpD0wusLib7GZhyh0ZAYAcfFgsNI4dEm5/fzbYYMiFsGouLkinTP29kyT75xB/Ei/IzhaY/sa1xEW1oGBs9sqBJf44SaUNhRG+bGFtuem9bFiaFY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; 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=ZeMmrnegfyxYKi8ypxIhybojRXBBc8QBpu5s+HtBvFfZBswSZR2lY1j2PdG5Zomh9vZMpZBQoVqFllRVyWxZTSxL44cwD92VHvbyKZCnklRLX9xK4uyLU5787INbJaynqeIZpY3bEwtu28IbRLCsYi7Xhp3PQFxRNNNyvJxwQck= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Hsl1GMRw; 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="Hsl1GMRw" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 06C46C19421; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=exjBpROHq5nt6ys/3V4S6O/quh/Jy14gJjvOKZLMHAo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Hsl1GMRweCxxcuyrSKMeI18gA591D6gGrSjKULWXkIVP0T4JZ8DE5Am27t4PyPvO9 PM9gACccKM4WSvM0nPbHuPBTIurBkHaTzyefsxZ8y4ZGqqpVcA3Rm8XWNPZw5c/vrp 6XY+23nSNynI8fq1IHXIhInRTA7i0JszdYhdceWbH657Fm6gocoOhq9jhoSoomROea XJKx7ZaHNJR7OrBnbOXzEVhdWDFDmkvkrV7arSwNmmHO8EzJuGxuZMiOUn6C6iU3q0 Z8yg+WnRdWtXhkgYG6XOjsak0WmhOxhHGRp1gUIcObuwER3NBZDGpIVHIiaTSnbRge kreUr3l3UChTQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043IB-0Vqe; Thu, 15 Jan 2026 16:40:40 +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 v2 01/15] docs: custom.css: prevent li marker to override text Date: Thu, 15 Jan 2026 16:40: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 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:13 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 51E6D3570AE; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=uSNd0REL+KUK1eXG78ZseTsWsm/Featu3QMdUh/OPHpe1dV0KWMc3bgGBSGNJPxRyscoYfp/aKDXCUSVl3xmMkfeEKniw6yJwkBrpK64FJzbMD+ozcd+CXTemAw+eWeBuzuDqBIVTcNt5C2zhqNyrHQgE+3jkrWFYANMztRVuac= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; c=relaxed/simple; bh=TCHwfk8ThCkFaLgmH3fFwJfEQHJ1oXz9bzKs/OW/Myg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=eGHqszTO22rc5u6jLu30z0sq4XSlzQARxrxI19WtZGR9x0745848zkCW6WiivDVIxo/IZJoiEp1+i+qjW4Bt+7Xa4Y2q1S7SzZM09saREZ87uyEl0/aMoBfNXAX26l0savjVDylCYlyneZGvqHjVMgnpG1gvKB/fahboGQtXfsg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=dQpcTweP; 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="dQpcTweP" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 0ABCFC16AAE; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=TCHwfk8ThCkFaLgmH3fFwJfEQHJ1oXz9bzKs/OW/Myg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=dQpcTwePp0HWy37rz5HnMQzk/fEX5PE24Pmo5QExdQbmd4ZVUwPD1J8+jau1s40mi w9/i1/T6bwDmP4INdUw5BXgEOcEHI1x2TQxt6BAOFdvSgzulWRg/Vy/A5c2W9rY7CL 9BIe4/Ma107GQ1G3MRxzS/WRyU8W2m09Myzas1td9OLEA1EQSxafX47zY/zHpogTsA 6WJRAYHen6DPuJ2DIwJsClUR6HJbdRDDlfeZ/4bRfjUYizquj8jPHqGdYXUZPEvI9A TYyTeKckemUOFgrL30YV/fOEHg62WO0/GF2lPTwmKhl2Aq6zK6LrDG9ym1oUXmMc3N I9wPfu+NnJGpw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043IF-0cno; Thu, 15 Jan 2026 16:40:40 +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 v2 02/15] docs: conf.py: don't use doctree with a different meaning Date: Thu, 15 Jan 2026 16:40:23 +0100 Message-ID: <34a3b676b2eaa58058a2578f5aa1427274fc633e.1768488832.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 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 1ea2ae5c6276..548e57b1fb01 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 [] @@ -70,7 +70,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("../"): @@ -80,7 +80,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("../"): @@ -92,7 +92,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 17:55:14 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 51EF936C0BB; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=JnmDTFOT0eYyDMehGOW1RIxcJ6KJWdNRZKvjzcysiLRmrkeI/Gbq91SGUPXSsQWpdGd231lgqr2BrmA+hONMy3Kv5I0aDz59Dt87VcMkG9uMgUgiM+Cbfq4kfGnSKCOoNiifIkTxQhx6fT/wzHnYk0fxm+CJn8P4HnVOwLebBfM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; c=relaxed/simple; bh=X8zMAMrZ2rBw2/CZgBSnLB3g6EePAZnuEoYA7VDGxVw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Ie3TJdgtOsh76I+uOAjjGIYnRQeUx++DpcsDksR0lji3yjSNjKvvq8R7CP7fydXt8eXtNW7vCIiyp4JGZFY8LUwh1KCVDkwx2GjuMU3WzPszwPPDos3lD84SNx1FIxb+EK73ENjXrax2iVZkiMlsSvlo5W8cbAt69fSDRybq27s= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=dGxa6w1K; 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="dGxa6w1K" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 02F83C116D0; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=X8zMAMrZ2rBw2/CZgBSnLB3g6EePAZnuEoYA7VDGxVw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=dGxa6w1KOdMP9L1iYgISs4fmGMEFr5/LoYZ9S+c6KKAEDLx2tbiAcfUOrPZCwqf+m u1suTMmt+YKt3Vd8shGPkQkGIM9qDf2WPPXZnZMQ29d/nOvaHaHqofRgP51QKYyluP ffQwaeAECmYxqX9ARplfuKs8E1ma20YcuSqXrfoeo9R/WQXz1k807hnB0qm3t9rtoS YHFsenebMhw3ecot8GqhIFnmgOFAeaFrW5DOufKT25xqC2KMQLWo7IE3Lqv+pHbRfd xO5zlhzeq4cmn5SsYN91qpAHKB/PdDds56jIaZAG/oX9S0o1LngTfwd8f3l7gvk0i9 RL3425TpA6F1g== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043IJ-0jbf; Thu, 15 Jan 2026 16:40:40 +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 v2 03/15] docs: conf: don't rely on cwd to get documentation location Date: Thu, 15 Jan 2026 16:40:24 +0100 Message-ID: <57823e4d8d025ad34e4891215e387778564fcdcb.1768488832.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 548e57b1fb01..f62982f83501 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 17:55:14 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 7D6443A9624; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=JsAaHNBOyc1a74IFt1j9lYr/i+1d4jovdM0RWNbMpJLbkzu3Kt5e2CDpz6jBe5XZ5yy/Jk+gW9yFioTue48UbSqr5SwU5j3w8g3JWrXMVOlgP6wfZj5+tGTZZCda1IFOIFt1rNw3Cm6QLSBoXP7J5PB5FjVjMRR94j5JhDxfoX4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; c=relaxed/simple; bh=EGAJHGENaYRvIcSMvAH/GUryVRHBlOYEI6qnDLTroFA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=CEchdAWj9nsfvmaYjpUMkMXMRhxMJRDEqR1xc2T+hV2PkhaHGBCGvuej7x/PhP2+C3jP4Zr2jAITpxG/eJ18o2zIBU+fZoNinFJQe769ho6ayG0iU5fm1sUciOglHe1LEpFQoxs/w7KtLEQ3rjeazXnsBht66/sRD/cd51x/FGk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=tgmShExX; 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="tgmShExX" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 17412C19423; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=EGAJHGENaYRvIcSMvAH/GUryVRHBlOYEI6qnDLTroFA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=tgmShExXO8jCKlxXKrrWqifOcZn5YF5RUeamya4WFeZNKGls7InOSj8YhOefCmg5h ZV8noJ2qUoqH43+LKD/OYupk0rFO6Ck8aSUEzw/XLol4DeY7y0e3l6f2ZRzYdPP6nc qZEtAogedyKeBz9FMZBbObEpEYrTxHKxxfFt9FN+EL/f9h4LEMGtxQ7RxPAK46kC3A r870LCE1Ag7duFb6vZHdFryszX8kcZjHcLzvcdstplBMrNoFI/uOXw5MHqIYG1tQse 6CN+xeJl1DilrpYHkJfHgYTdjXDL04EsTiD9E+FAUZiWUtoh8faulUn1yepF35lGZw YACzoQhMYZKHQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043IN-0qN3; Thu, 15 Jan 2026 16:40:40 +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 v2 04/15] docs: enable Sphinx autodoc extension to allow documenting python Date: Thu, 15 Jan 2026 16:40:25 +0100 Message-ID: <954a544ed6222bafcce2f3761dfc6b77bf9140f8.1768488832.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 f62982f83501..687c61e9ac7b 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 @@ -149,6 +153,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:14 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 7D5B53A9018; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=u1C/Jx9TncEoteNMYYshYNtXamM4XcrWIdBsF3dVZqzy+kCokyhb5aVaFZGPCGbTBvt90Bn4OIaeM5nKmPxugbOQngVWTQ75Fu4KA+7SChBFOn2cdKKKM+uQcU9+Gor5AKswF3VmwYaVbCNUgWMYHHlTH9QxN2Eu+tWQRIlrRZ4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; c=relaxed/simple; bh=wfHr9wNKFyYIJ5Okyj5woYiW9cOVx06PeOms6PzwjSI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=cthT9BdN/sof0BRPTRECtRHDy9z5NliFlYR+mjmVDrFAIG12ZESKkvuYalXAIxdp9c4cQGXLrBGVOEgqLR/ZFQDT0+UfBJjc+COVQc8O+HEmlxZwRUN/IN1NBOaULREyh7vjN37kVrlg789mGTdmEtYVA1QDBfrgSYLxNnbwlpI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=cdNlmbUB; 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="cdNlmbUB" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1DE4FC4AF09; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=wfHr9wNKFyYIJ5Okyj5woYiW9cOVx06PeOms6PzwjSI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=cdNlmbUBY1jWaSe1zerRKj86aUUd3m8zgcyfc+oBz8C79/xnal35X2MkAFT5q8jZa u9OrGo7J9tMWl4BlGVIy6L5YwydqkQg7gHyma8ygvitQ3V5ZS4JLPML0ihe2eeKcTA ogRvXS/DkQkVCiresOdHu3GADkPGFJ13pA0zzaw2yENi/qCi5i5hi8ogLhtnhKwzQH yOWIp04RRxI735NIxw3mzNm3Vf8ZYyjBIzRik0RNU55Z09iMnH9dOXyVyzXhjxNb+m HsZua/Rbg8dVuESiJ/D5qYEoYypZKWh4SoEas+w6HHSa6iB6uVPX6Me1B+bk4p8OJW OQBVsr15R2EBg== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043IR-0xIu; Thu, 15 Jan 2026 16:40:40 +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 v2 05/15] docs: custom.css: add CSS for python Date: Thu, 15 Jan 2026 16:40:26 +0100 Message-ID: <3a7f2f28cfdc0ff95ed8997b407d6f1d5375b04b.1768488832.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:14 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 7D6E13A9D97; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=T8ahRIQXHu1GIh/pMnjMriOpwgooHfPTv1gFH2flyAWAQWvJkGjXXx7oQrVGZswwCNScXwBi9wteXKoBzAfKx5wEzc4kp7ThxG/cAfGl6NOPwsThy8nIPiSFBtOnEj7/iktzbhMTphh9J4DeDzZ1+h21eNG5nTPvvH3ZLMjDpvk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; 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=YnDt+VzNu2phLr7ST6P2HzK8HqfeE1qxksUFj8eNKuPneAFelc+ry7vVIO7WLx+pxAtJLulKHxuNozCLq769M7d4nXlvOXNaujssiw+fiMIF7de9ta8QFKIcOHDeKCHXTXunuYSka6Y6P0KDpadojYRzV9pRYLzZ1khzzdCYA2Y= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=S/i8IiiM; 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="S/i8IiiM" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1E4E9C4AF0B; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=V/BLZs4Nlt58GEgPnSOwtNktnB67g/V/fdysHWNMdM0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=S/i8IiiM1TAnp2+cfeeZudPMcIcNvhK35D/OXwYUY8aISz2eqMNRZzodENjCWvLd/ LOuX/PJfqPyH05nWaBCkrs5NmZgLnsqKr88azhHfaMqF/vZFzNpYyNujVSAfeOdYeh N+fPW9dwov3a/Qb3TZ0M18tiwePf7RemcpTQ1Hyor48r+lLDKZUIeoXPD8ER5ZNJMN VI6s1Ij+S+BEIJBonRLErHEI0UebtaAt8UyOZJPggsYw7K1Q9vmhGkw2LY09lGTNy/ svIOdccv/k94PGUmKbVQp2Cq33HVM8FFyPEaV6mBCxo9QDgvzaiRZre3d8QdjvDeAB PdjYOughB/bUg== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043IV-14JY; Thu, 15 Jan 2026 16:40:40 +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 v2 06/15] docs: kdoc: latex_fonts: Improve docstrings and comments Date: Thu, 15 Jan 2026 16:40:27 +0100 Message-ID: <07a7dfd6c78f1b884cb5f4bb3a367e10a43d832b.1768488832.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:14 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 51CFD34575A; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=slN8wIurFbDInND9ettdqZJTwLk0N/TDe7xJdi4TtXUYSU/C2tmcLQAQW8ulGzfR78lZ3GOOr1yXuw9iYZHW5EJStEPzbF/O16pqTr6HuqLKudN6AlSFTPLEYynZ1vyGh7CsBpkINc++c9Fzw9laYKjbQum2E1S9mxs1eQnu6Mo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; c=relaxed/simple; bh=D20byBH6Dc3S8kqec0afWoBETHqoICKqefEL4fRTSCc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=FICCqs8G633+Ez7XJpX5T9xGu3hmi//v2mn7tHSGBB1nmAmDFDb+NyovT9QWZFfrUFisRNAn4fGAqUPZJ1kHRYYqASvXfQkIPj/HsO/SY0FFmVQZRo7dqdgL4fwSftqWqwAM+Rz0ic5yUtimeKZrkQF14AieYYJct2eZ7jzNu/o= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=chRPCMEA; 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="chRPCMEA" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1509BC2BC87; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=D20byBH6Dc3S8kqec0afWoBETHqoICKqefEL4fRTSCc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=chRPCMEA/qk4UuU036GaQNrBNwXGrhP0dcFpd9iZtppyTFdzbbEhlYvL219bqWVd3 q5ln/JkpORaXYLe1hiuV9PlArR0cxWHaxSzyqbGMiGUzyjlVM8x9Ja6amfSMdrIHIG UY+gqnVCQ3gkv+8U5uQiZwyF0HQxZeXGMUnBGqhG6ZAHUsOYGOEfynV4Mxsdy0tdMk USqE8KmM9ayEzShFYUh4O65y/zsNZUZadrHxj/HkvcqHvQ2fqVRXT4mWbHwxElfg6X 2HbTkOk8mBfZMzvCmdSc7CN5I/Vq2zHaCu5+ujnVWojgC5kRRqRproEML7LulvhGF1 vQI1AoOPaB5aQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043IZ-1B5k; Thu, 15 Jan 2026 16:40:40 +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 v2 07/15] docs: kdoc_files: Improve docstrings and comments Date: Thu, 15 Jan 2026 16:40:28 +0100 Message-ID: <003d4df10446d545113c6361755da99915bcf321.1768488832.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:14 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 7D8C03A9DA3; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=dGaWvafYG2TGUC9hhKAm4uMsUL1pltDnLL+0MFWJlaXjnpkJnpnJNLjKsI97Qj/EjSLKhy+IpIHZCJG04T0Rjzju/V6D6MIogSmsYoiHoqLpdeDzFZEE5kX8pxP7TaSH/i7ny5MOZjZBl9ZKLgwv4h6ZUaH5NMqGbiSuBqNWdiY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; c=relaxed/simple; bh=kmk1GvA8qQBm6LrMB53lcAYigASy9DuUwFJjdBAuCYA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=AXURSySrZK8smMWjs690xwpfMt6YMaqKyFTKt7fsAQm8ultOv8P1J59YunARlorWL4C31Mza1MdPOkRYGeTTWI6K1hfCazjzoZJMwqf3OaRcoicLvqGsJwZTR3O09u1boc3+zRXX79kj7MvxO4x92SLK/dV+ywuhsU4MssyRBU4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=VOChNeqZ; 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="VOChNeqZ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 19ACAC2BC9E; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=kmk1GvA8qQBm6LrMB53lcAYigASy9DuUwFJjdBAuCYA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=VOChNeqZjsMGc4p/t/QMppcsIXTzVj80ELNAdbuL0Zpkm2NAAaw7ZFf5qBz4bHxYv YSsFyurw46vk0QQtyOOnVPMfvEVztOgyG/Fxzqi8+STYqAA493Wl4yGA9+E/0IW18C g9nSCWYwOoiHxSM6wXwczSL79KRMJxUtT6uizJh611mIcBdku5nNwxLEM1sZ9mzdUa HzQT2TCT1tRRcwwR30w+BHbvAB9+vLohgDm3e7I3XtO02/erG6RopCP/7UnXOPXcEe 9ZYhmORr0eghmh3MW7B1DA6bggrl+7+enRsCf/gh1hahj35MKOzYlyG1kurkVbv8Oa BX5ER/4NRIzMg== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043Id-1Hsl; Thu, 15 Jan 2026 16:40:40 +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 v2 08/15] docs: kdoc_item: Improve docstrings and comments Date: Thu, 15 Jan 2026 16:40:29 +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_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:14 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 A108F3B52FC; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=MvxbT3PHvPD4lrSc6pX2FNCfO9WzW5rv0JpS03UI4p9m0EQySOJa/HdJ/kHWr6Ml6Rr95n1+kdtXbS4093KRO62vLbWHn654hq9jkN3YeeONIwDl0e0CaHliIeNvCAzph3WiT02THhYhS/tgURPEplCVANGDCPe/XNEOOauuY3U= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; 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=TM+vvAVJt/lmk59Rkg+hD+0OOLS81/YbSlkJh7B11WtArJkLsX46OsSszCKR/zV8uMRF5sCOd+HuI1XLQATwlXzUJNDjeXumMjCwGR+qKfm70/WcVB2iPgrJad4UshwUApy0oG0JLBbbftOV3mpz9uJg5QCyQD9+B0fLY5+vOoY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=a2ZqJKlj; 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="a2ZqJKlj" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1BD8CC2BCB0; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=xzN+qnwUzc8uS+xH26py+FM48k+pV86aU/2bH+RENHY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=a2ZqJKljQvQPtAjFXbbjB1XjOH7tc5AJsrAg9wC/KZCm3Oli5AaTxjZrAqrNI6lXx t9c888bdiGhFvaGiIH3FuLwp5Fm7ATaXjYQuZZZ+3XWdynReSIwr0Qfe6XWAEXXbYV +2v5uHY/zsfXcjGAgZB3EULSOFPJOQecuJA4NF3wlF4Q3NKWMVA5CUEBdBYferrzXx jAKWUsCoTNhAjs68oT5weDRFKvTiZ6vP74i+Y/4owegor3cgH4Bc62x/bgrdxygO/J 2QaI76RPZUy+QJH0uN2Ur4+iEnqS3UBh41N0lFhR+2Q2do7r2mVMek68gFSL3U2SbE +TGa+0ND031BA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043Ih-1OhS; Thu, 15 Jan 2026 16:40:40 +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 v2 09/15] docs: kdoc_parser: Improve docstrings and comments Date: Thu, 15 Jan 2026 16:40:30 +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 17:55:14 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 7C4773A8FE5; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=KcwfYLN3aJr6DIJoIHLHuo0piEx+XBr6BNvfpxdu9hGZxsGOxCQ5xkgNJypDGZXTZr2NgWgfz75pCrA3+AYlpegjJMGdyODOJCaHnwaaZS7r7ZMS9AJ0YdLl0g41VnhZxp/C7TSZYBaHM5NNMUF1Hjpns2dVe4vUVeNr5y1cGOw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; 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=rJbZlTI2zvJAxJ6pkVGm4ESUHoAioTvTesHwIR6S6GtXTgU3cd2dtEVsO3bqXX0parifzQ8bp+7lYOsXUsup5hPiawxszfktTx4LNMJwktZwvjRRG7rCUzPx7gZk0K0OYeMnbkyotNfAI240kzhjn88uiJbAPu2rcCD5U1ZMDUs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=V5ssH+Ux; 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="V5ssH+Ux" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 131C5C2BC86; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=FI+Dh9Iu2wtKz8NU+WdlvdtlEUg2nNsIV9O2y+kNbi8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=V5ssH+UxPd3GxI86XybH9H4yQzOqokD2CoYlfRslYava5v5DyG0KxGwB1L2AjIoM7 Y1lL/HPrHQaUkE+ymGeBL2YF9cTuPcMB0aXzxrNY7FXiFddjRTgAAo+7UrHek3RQn/ CR8Qtnd1isKTMPOquMIbCyB5EFTKeRowOwtfXmJEmK5HBY8uFkZ8iQv3fEoqNqvoDo CRpo1qryl/n67ebdbrN8ui5iqwY2RsfzrX94Q8wWx/LQ8Z0UnihJZWpS2hSD0yAkZw 77OeIGTZUrQuU/OuxqYGVeh7RkNkQOSVQZxyVr1+tvsa6WCSChnqirVyOAdWHDviOK F3npl2dTsmCdw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043Il-1VZH; Thu, 15 Jan 2026 16:40:40 +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 v2 10/15] docs: kdoc_output: Improve docstrings and comments Date: Thu, 15 Jan 2026 16:40:31 +0100 Message-ID: <4b1dbe22622af93982b451a4c6b459f49f9d2bb5.1768488832.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:14 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 7C3D33A89AC; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=H7ESJHvu3SNpsj4FCQqPlsa0QzwS8H7VN6moYg3aGn3dbCyy3LzMP+c2OhYK6Snh4aHQ7gnRnlSbzk80APUG9J8rrhKe2hCWppR2PVf1uOn72oMW6rOR0fJYPo1fAKSzgsq1ZfFgzlo09yDyFTkgXPbAcKF4NnVW5zrZEVM2Fxs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; c=relaxed/simple; bh=AT9QRc72PaX75+hy9TLUQhCbT/HxXyi982eiR6wBTwU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Uw8WQCVywI73oYuML3P4J8uAHi3/GqWVorEUqJZ8Wiq4kaawz801U72EzKfvPO4LIo7UFwCpnidAYEQQZ9F/SBSojUEYADwXHhceWIvYOHhpqrLmpPvuxZuq9ExDy7jOel4QmAdtEH7WFYyVueN1rCs0mLxTdMPgyeYyuZDAHEg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=WRpK3+QW; 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="WRpK3+QW" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 20DACC4AF0C; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=AT9QRc72PaX75+hy9TLUQhCbT/HxXyi982eiR6wBTwU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=WRpK3+QWOy6MVTdxcWdq0iU9jXh75g7sTejc5OrEPYor/vKF9iOb7M+5plYxoQ6+y 6QJH9MLmWJEALUZ5dNPraJVwXAiWKcBvvV0NPyv8/88HbGX0VaJ0Jw/GlK9xpe89Fb om/FQhzS1Cni6eXc3+41JQAxob+JYvvFFOOJb7AH0GDYVQxO5KArsyoialeMxzFC7H f7vascmuu8ANKkqY/3I5en1853LyIsSvO/qKWiTKaAIFrECpeDYJup+6cfY8ZYgRJ2 HARIOnJXETZ6AlO7YyBVy2e/6mKUJfBv8UkpVVwSqNQU1rVf0CAk4mH+j3oMPZzr28 6sFyJ8jbXoRxA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043Ip-1cKG; Thu, 15 Jan 2026 16:40:40 +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 v2 11/15] docs: kdoc_re: Improve docstrings and comments Date: Thu, 15 Jan 2026 16:40:32 +0100 Message-ID: <2303354f22b1630975f1fc907b651ee336f022bb.1768488832.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 17:55:14 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 7D9C53AA1AA; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=RmssOi6uhMpNfZFyTapZ70d7maUsZYyEKqSCCtJg3O5txx4EiHzXTLoE+1iU9P6JhB8iiIfP301SmNCyfkrh6UglLXimj7zs8U8xo2PZIiMnGiZYBZ6+fFLS8OUWWR8XZ2gpj0LitPIcIyRqzfiJEVn1voqnU8mFG/hHdKj7/mA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; c=relaxed/simple; bh=i1tcZCaxJM2MU0fiO/S47vsflPzYkddGYteNjd18qHw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ncINNDZIxyyvFzFbCDyvNHd5L4SZ2VM7ibBue6FZCg4aGpDUDGS+w96WJ48pgp5A2a9w71RvMdpbg4l9mpC7YI9MCISANzjeQkhik4jVSc7u1+nJPYEWswQ/at30Gok8z8/4tRgHUbbHPkayVG/e0S8792aSYRd924WW61ED9Qs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=G96KHlOd; 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="G96KHlOd" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 22136C2BCB1; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=i1tcZCaxJM2MU0fiO/S47vsflPzYkddGYteNjd18qHw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=G96KHlOdkwqcE7M0bta2YtY+/0hCe4qQtNb8PMvha3wAvXEm+6sGE2eJ7y88RkDx2 rjNHwkidXUnol4368x87s6mPp0tVY/Pvcsp7JxR00Oaq12MW2CzZHM985jjiao3R7z e/u4AMH8jJ4l5Vkbq3yDJls85ElfMVBnq2sjC7634a8iK7A9J6cOasX3mCiJAPrEdd Wbgdqs755Xn5IKQUy72+QqyC/wnEykPIe1NffDNvA9OSl166EaGCTvvClRY+HYuyeU gRofAvM23PyNhzJIKMS4TTo1/J90lojHlv6UL/ET+GwOkTtaqEvdUbgAdoexrLw3L6 tjsyVBWTPfKOw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043It-1jAP; Thu, 15 Jan 2026 16:40:40 +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 v2 12/15] docs: kdoc: parse_data_structs: Improve docstrings and comments Date: Thu, 15 Jan 2026 16:40:33 +0100 Message-ID: <6a613960686d6ff0377f7365f7f547c31d487593.1768488832.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:14 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 7E2433AA1BB; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=g1/n1obGGYj1wNSmfLhJagRz1iKx6vM1Rbw6dp4Bn/flBsZmjfobWeCdk0QZepxaLSqNGs37S3g3AX5t2k0+pJAyzir87kRwpkoSqPwpKLedPuI7ipFnqRnkUQ+dOg5/0gJJIX2tRAJsrZIGbp0Cd1Hy7Em5LM2WuYXgUEigFvM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; c=relaxed/simple; bh=EJEpOIpo13K5wVlZXAiPofrL9GMVio3Ohn/l0ADAKD4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Y7QHgY5dydQjeOoPtb70iDoSRf/m1FRFY8zVosqbCGAqKEbYE9SaWIWaaASNiYfFJnhs2xgcYjlBtHcz3OSH6Le3sC0n9G/KJ8GdhP8kTrGW8gbGlFtM2zhAJqxegSA/uQBjo4d3gAAk8BiZjgs//O7VAGoK3vhJGM6u9wNTDr4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=QWwf3jjO; 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="QWwf3jjO" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 28CBFC2BCB7; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=EJEpOIpo13K5wVlZXAiPofrL9GMVio3Ohn/l0ADAKD4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=QWwf3jjOqk47/1cxMVnSrykfiOhxFUiF8UHuGLf59mgTCvEdf72WPMqh5J5NnFrzz 3qcAUlAH5SEzFVXaOwDthV6CtblTdljpFWJdzcz5R/S5kFAKW6gPO4C10HkkBAiQ9t 0vm3yRgbdTgGMV64Qzids6GOV/WUEcIhihMatnuDSYKcKKbG2JammHdBWXI4cjg1vp kSA8r4f1VeKazvb9zZDQwOp7Lp/qQeDqRLVXMmhHxBQvDeqT4aDkW3vEF5P6Hlib+R RddWXgTsXL40mPjDjxGgEkQdGgpu9fWpPMNYFG0dVJ5kYSEnNh9hyqOtvt65NA2gsw 0cYuis0xjck3g== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043Ix-1q1O; Thu, 15 Jan 2026 16:40:40 +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 v2 13/15] docs: kdoc: enrich_formatter: Improve docstrings and comments Date: Thu, 15 Jan 2026 16:40:34 +0100 Message-ID: <2de09ecb216c187beb5aac72041fa1a9e8380173.1768488832.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 17:55:14 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 7E9463ACF12; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=POsk1x2Y6C5OyNXPxQX3tReaoJW1P2weFdQulWRXGFseZ7P8iB746alR+rDSh6lqBFCmJ54gduqdERA13WmE+gr5okziUrq1pSLfTLsq2fQyi/LXqL3Zw7/8KkCf2YyJ0SJG4vFfkX+iG8lQRuWGxZD1yju7R/lPZEj3IICB1+k= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; c=relaxed/simple; bh=qeD2CxushaNmzGduOrZz2GnZPSRsopACODszEDevkew=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=JLIzrtdKbhQfUeAOOgL3bVjjDcVlbjDJEQ02QoWhfalzXuibMMA3dsxRuVDFUGXrNp24wEvVbJG5yOfvWfStQ6ihzKMJBhvjwigupUbQE3uS/BUyzT6cpw/NWBh7HcMXFPa4uXiRAs1gZ04XMd/e+JvM5nOqH10vhYh57KaC96I= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=s4qL0sM5; 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="s4qL0sM5" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 325F1C4AF0D; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=qeD2CxushaNmzGduOrZz2GnZPSRsopACODszEDevkew=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=s4qL0sM5okyH0oUGSgP0m0xmk89HRsmoIily9HKJ5uMw8QDdMkrhbBJX4PWTCRY3v 5+mqr+xjtshQA1zfAS/rfeXBkhj5oTTVEsga7aIiWPBXwQtmMEU5A9lHeteBCKpW0t oS7GTKb5MRsZQp89op3SsDMGRf2MrWxdVUdxUrV/Drb8Cf9LMhtIyZVqrufCWDoTKe AtSZTRMOQ71gJYlwBBJP0Cx5NJOaES+WNmdTtgHBuFLRJ0pk0cFbl8ZZheXqZyaT1K uicznAnWAlj6ONTjmtRKfus3gnfgRpqKbgiCEMxRuACNd2paAnKk82BQxCOST5bIH+ QjTZefIwU84oA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043J1-1woA; Thu, 15 Jan 2026 16:40:40 +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 v2 14/15] docs: kdoc: python_version: Improve docstrings and comments Date: Thu, 15 Jan 2026 16:40:35 +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/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:14 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 A10003B52ED; Thu, 15 Jan 2026 15:40:42 +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=1768491642; cv=none; b=QWT+UWond5ZQd27dhzjK3QVPP5hpjkziwTz/CE83iQ1abDPgiK8pDZ672R7kEucLUxBtdtAInDYSIunn6lb+FnPD8ZjK2iXv7SrYm0Vpn7e9usxp3MEkeZyODIsPywEv3cyJKi/OP9r0fWJxtK46y7OUzVVmEwIZXFSDWtD+HK0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; c=relaxed/simple; bh=s1mjnTzuhsFarODXcVZv6x/pyTkp3qp8CK9/urSRqTw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=UCLMB0mENSNfgDpmwgN1v6JGifAc2hben79a/oqcA+uyUCN1tbCIYhxraLjVzQ8kBeGkEtpZlG2350iErnpp0iQ3/7HKs16RqgesVl4PoZtUE4K/Pzlh6voEFwxyO+prvL17ek8k1iY8fUpyb/qiBrrKIF6oLQoZ6C/U7Ef1D9k= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=AyGDhR6X; 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="AyGDhR6X" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 39B1BC2BCF4; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=s1mjnTzuhsFarODXcVZv6x/pyTkp3qp8CK9/urSRqTw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=AyGDhR6Xc0NypbnxoAy9EeWvLcMs+49KdrlslDyGpkqgSmVkaZ+xRFuztBQk2ZQSW 9i9PL82IvRUC8j44AfiR77JpVhcK5+BA4A1abmWrQhvY3idtPeFJg7LuelT6tJk6Qt Qsd6tGH/3/g5P9o6+hpxTnfV6MiV75UzWhmeOG2H+kWP4XD3cUQGqB21W3s1xMho77 yFs7/TIHSt2ARKoTCind5eD9vDza/44IbY8uSLv9KAq1T0rTEVNqxV4bo9le4u1HC4 vwy+UCWXQckLfZBE29VgKJjC79C+wgy+bCsb8haUG5Z+rRj3/EdIRqyEI5+kQj+g24 vkRFUEuD+z/BA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043J5-23g0; Thu, 15 Jan 2026 16:40:40 +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 v2 15/15] docs: add kernel-doc modules documentation Date: Thu, 15 Jan 2026 16:40:36 +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