From nobody Thu Apr 9 21:49:32 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 7A2C93C196C; Thu, 5 Mar 2026 15:16:27 +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=1772723787; cv=none; b=Ytgg7406srb416HHLnPVQruRsYQu/oVy3SjgVtahWugs3qmtDj4Tkp+WpX+hvV5vAFH1DBbfmYfTDITvDqch8M6vAYUBDLv+8m8ND7JhOgf/jifScpTVrDoo9yUa3EiAMUuyeRTgTCaPmwyoRwb4duh1Onr1G7xctOBKKSIAcnE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772723787; c=relaxed/simple; bh=P6Q2PSaD8E24gYpLDm2SuaDxRi4gZVBuOO+lyWBKM/E=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Ds036dAKct/EY0bGHZpZTg1E3tHBQKiUfVQ7AfO+e21V12EaN0nv0Y0780O4CvLqSZBANOHuYjYYbS1rdXpOD36vU79K6LLQeXO+6kXbt54Rp8faHFd/mMYV14R0Av3mc/nztfxYweHWi9bxxxQQQTDGxcqW9IL1hCMvhKgVPjM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=gbrFTJCK; 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="gbrFTJCK" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3BF4DC2BCB5; Thu, 5 Mar 2026 15:16:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772723787; bh=P6Q2PSaD8E24gYpLDm2SuaDxRi4gZVBuOO+lyWBKM/E=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=gbrFTJCKrPKn7HZ8lAAey0jUh0JmONDLVJxmxOmVb6ZrK8UGU9S6DjlTrbQPePKwU b/yj2N3Jws7/I/r/2fXw+avz55zjfYYLJrOCkw85Vkj4+wUd9GeIqaTluipTGWPNq8 nAHZ17H/xoRXAENb/R6bcGeT6IPBrK36f/QVM0sVwH1WajG+DLhlNEeVsVFkgfmgU4 UooKxm9xzc+wZQOVOupAHi9dQySDzFHjbUaVvTGUwEEspgp2PtW9MyCnKJ/C5VIRCk rmiF09UqomiVTr3CwIP2UUX1lGA+tOPCZx9j8xz9eWDjqi2yAuApKaBzRRgb3eLkLZ MuAPONgMG7oyQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyAR7-0000000HK2t-0qCn; Thu, 05 Mar 2026 16:16:25 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Randy Dunlap Subject: [PATCH 01/11] docs: kdoc_files: allows the caller to use a different xforms class Date: Thu, 5 Mar 2026 16:16:08 +0100 Message-ID: <6b274ddbdcd9d438c6848e00e410a2f65ef80ec2.1772722474.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 While the main goal for kernel-doc is to be used inside the Linux Kernel, other open source projects could benefit for it. That's currently the case of QEMU, which has a fork, mainly due to two reasons: - they need an extra C function transform rule; - they handle the html output a little bit different. Add an extra optional argument to make easier for the code to be shared, as, with that, QEMU can just create a new derivated class that will contain its specific rulesets, and just copy the remaining kernel-doc files as-is. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_files.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kd= oc_files.py index 33618c6abec2..c35e033cf123 100644 --- a/tools/lib/python/kdoc/kdoc_files.py +++ b/tools/lib/python/kdoc/kdoc_files.py @@ -118,7 +118,7 @@ class KernelFiles(): if fname in self.files: return =20 - doc =3D KernelDoc(self.config, fname, CTransforms()) + doc =3D KernelDoc(self.config, fname, self.xforms) export_table, entries =3D doc.parse_kdoc() =20 self.export_table[fname] =3D export_table @@ -154,7 +154,7 @@ class KernelFiles(): =20 self.error(f"Cannot find file {fname}") =20 - def __init__(self, verbose=3DFalse, out_style=3DNone, + def __init__(self, verbose=3DFalse, out_style=3DNone, xforms=3DNone, werror=3DFalse, wreturn=3DFalse, wshort_desc=3DFalse, wcontents_before_sections=3DFalse, logger=3DNone): @@ -193,6 +193,11 @@ class KernelFiles(): self.config.wshort_desc =3D wshort_desc self.config.wcontents_before_sections =3D wcontents_before_sections =20 + if xforms: + self.xforms =3D xforms + else: + self.xforms =3D CTransforms() + if not logger: self.config.log =3D logging.getLogger("kernel-doc") else: --=20 2.52.0 From nobody Thu Apr 9 21:49:32 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 79F993BFE47; Thu, 5 Mar 2026 15:16:27 +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=1772723787; cv=none; b=D7+Q3WdPC7OcRNkFgk8czvLa/iX4692NFWAHKNhcdrrlc03vrR28iMpnHtJCtaf9k2mPLonFRbSeHIiGygWJNMGjmC/0MOlVTyf05Bw1MGr48VFbmdzKJJ3ExeP12ozMzCxvcM5Gk6NGRn6HKUlv5JEOecN6Co9/PnLzNe/TZ/I= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772723787; c=relaxed/simple; bh=93FI6HCbFuKLoTGysvIesP/671jVJYX05qdlxtKR9Kk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=acFBYPhx9xyYTvSOr4Ap5fDCyiDEBERqkG6+ItfpKgIqIo2mZXVmxfnf6HuJAK5WuwDXgFUgjKaAfCqFSOfKXqFLP/AjfJRWjP7IbQrUMNiLpfQBcD5W/gccpY/XEUHQ5j+SP+luam3SIG5oGmmucXA72Dtlq+n9evE/y4IMi8s= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=pH+V+/4B; 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="pH+V+/4B" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 34E5AC2BCB6; Thu, 5 Mar 2026 15:16:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772723787; bh=93FI6HCbFuKLoTGysvIesP/671jVJYX05qdlxtKR9Kk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=pH+V+/4Bk982XSdmUrwHswZNof74somChmhKuPNiywIUOHvNGtgOA+o3i7J8TzNKO yi+dNuAlSEsTqtIbo/pn874vqoPJTXRk9S5+zMXavwtZGl9vkX9JdNpggsKkHNZuny e4Wt7Rf7cg75xnwKEMRO8ehhcf52eumz4ymBslx81yGsv4RsG0lAv1jW2RpTsTOSYl twBa0Omt4lBasTlvLIasaAXUjCcOlcZVcMtervnwQHzNnFbJWv0fQd+jKDUxW+V81R IWe6JvtO5Cl2kcn8nxQ3mJO3BKCCO3ZZ4n80TlSvVxkvSzSBLpTB2Pu4GOvOhoVvTr 8jhFl11t8GJ7g== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyAR7-0000000HK46-1hMN; Thu, 05 Mar 2026 16:16:25 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Randy Dunlap Subject: [PATCH 02/11] docs: kdoc_files: document KernelFiles() ABI Date: Thu, 5 Mar 2026 16:16:09 +0100 Message-ID: <13eb44c341232564eaf2a9c9de4782369fef57e1.1772722474.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The KernelFiles is the main entry point to run kernel-doc, being used by both tools/docs/kernel-doc and Documentation/sphinx/kerneldoc.py. It is also used on QEMU, which also uses the kernel-doc libraries from tools/lib/python/kdoc. Properly describe its ABI contract. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_files.py | 44 ++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kd= oc_files.py index c35e033cf123..8c2059623949 100644 --- a/tools/lib/python/kdoc/kdoc_files.py +++ b/tools/lib/python/kdoc/kdoc_files.py @@ -91,7 +91,49 @@ class KernelFiles(): """ Parse kernel-doc tags on multiple kernel source files. =20 - There are two type of parsers defined here: + This is the main entry point to run kernel-doc. This class is initiali= zed + using a series of optional arguments: + + ``verbose`` + If True, enables kernel-doc verbosity. Default: False. + + ``out_style`` + Class to be used to format output. If None (default), + only report errors. + + ``xforms`` + Transforms to be applied to C prototypes and data structs. + If not specified, defaults to xforms =3D CFunction() + + ``werror`` + If True, treat warnings as errors, retuning an error code on warni= ngs. + + Default: False. + + ``wreturn`` + If True, warns about the lack of a return markup on functions. + + Default: False. + ``wshort_desc`` + If True, warns if initial short description is missing. + + Default: False. + + ``wcontents_before_sections`` + If True, warn if there are contents before sections (deprecated). + This option is kept just for backward-compatibility, but it does + nothing, neither here nor at the original Perl script. + + Default: False. + + ``logger`` + Optional logger class instance. + + If not specified, defaults to use: ``logging.getLogger("kernel-doc= ")`` + + Note: + 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*`` macro= s. --=20 2.52.0 From nobody Thu Apr 9 21:49:32 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 A451F3C2760; Thu, 5 Mar 2026 15:16:27 +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=1772723787; cv=none; b=pqK0J44Qx3OMbYxwyhbEgEYXK4aGYg7nkwnmznHhK5lzTk40RqTmLWvQ/cJxMpyhr5FAkutqbWinxXVYxRHoyQyTZHhaH4EdSjoPaDbTtSgvxeTOAwHcqqkH/JXV8Un4E5624B3LC39umRzSETbeBDI6AcqeiL1YbWdkuAvo3K8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772723787; c=relaxed/simple; bh=J9gpBcUhWSmksHEje7HfFrvd/UJKiZjrUhxoxqAfK3o=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=KRJC8XZfZjmQZeb0h063kz2efby3xNYLGrDOqQkwjFvZWyeZptvNAgOz/yRbkYUsbku9zeislPVgw8yZKJiCpVEZJynJnBcg3xaTr+cByZV4+u/5Z7DLSn8RA0VxaSXynA7Q9X/LfAFLKF72gaC1mT5um7u7hwjU+tLKkuNWfSI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Qe+XJMPk; 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="Qe+XJMPk" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 55EF2C2BCC9; Thu, 5 Mar 2026 15:16:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772723787; bh=J9gpBcUhWSmksHEje7HfFrvd/UJKiZjrUhxoxqAfK3o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Qe+XJMPkMOKvN00ZZXQ2GyvcXqPtPdJwYyv4ACjAPFa7NNONL99ziy9DcRmL9MbKm ZoQT1G+lTHUCXUPSZsSArf4vLScwAx5jqZR/6iDruhA7E7l9LkVL+q1Olz1Le+xGRq BcAk5zXAJnOmZDJv61U+j88w0ivZHxub8LtrazguCUvFT4V574Xrdeo9GfEFUX3RrZ DShEfaTcbPd+s+baonbwk7PCkcNMAciv7J7xJbpWTGODOp6lyUHLqxJR+oGFS/4Nx5 ufRfjRjlGq176tP0pbPDHxLq2OUNqIRSvg4MQFx0npS5Shj5Yq3U02GonIidLdRVw8 oIe0pJO/nwlIw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyAR7-0000000HK5J-2Yl6; Thu, 05 Mar 2026 16:16:25 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Shuah Khan Subject: [PATCH 03/11] docs: sphinx-build-wrapper: better handle troff .TH markups Date: Thu, 5 Mar 2026 16:16:10 +0100 Message-ID: <9436806316d33aaf68625c00ce068463d3917660.1772722474.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 Using a regular expression to match .TH is problematic, as it doesn't handle well quotation marks. Use shlex instead. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/sphinx-build-wrapper | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index b7c149dff06b..e6418e22e2ff 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -576,7 +576,6 @@ class SphinxBuilder: """ =20 re_kernel_doc =3D re.compile(r"^\.\.\s+kernel-doc::\s*(\S+)") - re_man =3D re.compile(r'^\.TH "[^"]*" (\d+) "([^"]*)"') =20 if docs_dir =3D=3D src_dir: # @@ -616,8 +615,7 @@ class SphinxBuilder: fp =3D None try: for line in result.stdout.split("\n"): - match =3D re_man.match(line) - if not match: + if not line.startswith(".TH"): if fp: fp.write(line + '\n') continue @@ -625,7 +623,9 @@ class SphinxBuilder: if fp: fp.close() =20 - fname =3D f"{output_dir}/{match.group(2)}.{match.group(1)}" + # Use shlex here, as it handles well parameters with commas + args =3D shlex.split(line) + fname =3D f"{output_dir}/{args[3]}.{args[2]}" =20 if self.verbose: print(f"Creating {fname}") --=20 2.52.0 From nobody Thu Apr 9 21:49:32 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 CF07F3C2770; Thu, 5 Mar 2026 15:16:27 +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=1772723787; cv=none; b=sjCWx6ue7Y6mpuOYR+2K/EYNZygrOUzxkEyFVJE8nbAfnJRkoOPHvMU1gy9GnKqEbH8TYSMwinPf6vBCC3FUt0eEWgbqyPQqAQ656zAcblEdfSiM2FJQ+tNvZZpFesBgITRytnPByKaTtAJJIZHDmktRCjO7xrUV4mQLAckSX2c= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772723787; c=relaxed/simple; bh=61zAS55bnxXfENb2njyTK755tLiXa/iuu9D4Kk7hvyY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=UHqPD4ogb8Q4SEAtPtNw7xT0cOKCARd9Y65yzaP8lnFCqDWqOUCezgDh6/AQRmHbs4s5KVxSZuiMalKqqA5DraHmzWBXtexsC91J/snWh5LZb1sCWAv8InUrKodGQGcGOfr7ksFWu4DKh1lcDG1cijKx+6ULBYstkQxnvNryIoE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=nDI2ZK5J; 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="nDI2ZK5J" Received: by smtp.kernel.org (Postfix) with ESMTPSA id ABF11C19423; Thu, 5 Mar 2026 15:16:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772723787; bh=61zAS55bnxXfENb2njyTK755tLiXa/iuu9D4Kk7hvyY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nDI2ZK5J+yEHe7kETLYbaHRy1nzbhFgte3dZIiTXPJXvQSjQKshOM0GVPtWkHuwie XfI+uLVtrOVo2/FPwDFKigmQkRgKytPKJytBpdlBSzTv7IYOQADYc9nYOv6P7eLdZK EYUTomQKMCnbZVanL6CE9PlWmWZpK/SBOZnxknOxfjr5JLkpzWTrsnxtsfSp+LbykJ +qDpxMDuG50feDnexee5og0NBey4tf7NhxhPspXNlIiThWl7R9pXQh811j2SMMroHd lcJtcBbcM/GxAbcQ0uBwTn6A905sY9SILsHksEyZtLronN4TrwJPbLvOYn+y3rZb5q 8a+fjxQS+bk1A== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyAR7-0000000HK6X-3PNt; Thu, 05 Mar 2026 16:16:25 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Shuah Khan Subject: [PATCH 04/11] docs: sphinx-build-wrapper: don't allow "/" on file names Date: Thu, 5 Mar 2026 16:16:11 +0100 Message-ID: <7dc8baef622ed93490f6b2c58e3349d9e105d08d.1772722474.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 When handling "DOC:" sections, slash characters may be there. Prevent using it at the file names, as this is used for directory separator. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/sphinx-build-wrapper | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index e6418e22e2ff..4572328e379d 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -625,6 +625,7 @@ class SphinxBuilder: =20 # Use shlex here, as it handles well parameters with commas args =3D shlex.split(line) + name =3D args[1].replace("/", " ") fname =3D f"{output_dir}/{args[3]}.{args[2]}" =20 if self.verbose: --=20 2.52.0 From nobody Thu Apr 9 21:49:32 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 E32493C2779; Thu, 5 Mar 2026 15:16:27 +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=1772723788; cv=none; b=jMiUKgsWmAB+oNyRHDYTzyfU64a+b4odKCGblCICzzSClGaGnJzRdiIebut3LOtN7Od1bxGm0/bkTq5D2e//WjZdMFOOLi/56EmgyLIpuRXRlzMCkOkuvC8kGr0LsAEUv7yVr4qqi4jO6gv3dfOE7kuXPODPGlXuA6VnUud1WqQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772723788; c=relaxed/simple; bh=XMzNqgRp0gmQJyWaL/t7SqMf5vJ/1MBUlDjM38i47fA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ZEHsKh21DadbvyUzxz8dFbvUoIcXaokVfowjhAfZu/SeXs5v/pFfGE3WYiPaGderfZj0FjC7qJylK/zraIFah50NpDDqODHh2vkBZESa87fKrKQhWkgW3wm1u322shziqdqe3oa7Hjh3vdKV3ALs3iP1YJrtAVAI700LHP6Ks2U= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=KdNfVPby; 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="KdNfVPby" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C0CD8C2BC87; Thu, 5 Mar 2026 15:16:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772723787; bh=XMzNqgRp0gmQJyWaL/t7SqMf5vJ/1MBUlDjM38i47fA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KdNfVPbyPdr0d+NmXpEOu+fcCEg2Mfni/3RH38q/ouRHzw7/OxuuPYInGCfNe22/d G68ni5ITQDErj0UFqN70yZThFiQfFSSBD4pC+J831CYoKGYK1vlQzNKanDr5uqeXHw ga4yWHizjxViVn+u4Ykdkg/UJL1DEXW0b9asqf0mMUBFFhqu6tpKf9APx8rSwc6nCT l8wzCNnmDCBRMC+5XpopXPJrE4jTWredCtXcdp9ry6mg2TJTW7f68V4xm2IDCv5Y4c BEezdBhcdvZuuS9iH29wcIjeePiTZ1mcuFnMLOLAwD5dSSkrgrU7nEYXhNefw/AQaE HRLjyg2h8CJdg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyAR8-0000000HK85-04Ci; Thu, 05 Mar 2026 16:16:26 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH 05/11] docs: kdoc_output: use a method to emit the .TH header Date: Thu, 5 Mar 2026 16:16:12 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab All man emit functions need to add a .TH header. Move the code to a common function, as we'll be addressing some issues at the common code. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 34 +++++++++++++++++++++------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 4210b91dde5f..fb6b90c54c8a 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -607,7 +607,20 @@ class ManFormat(OutputFormat): "%m %d %Y", ] =20 - def __init__(self, modulename): + def emit_th(self, name, modulename =3D None, manual=3DNone): + """Emit a title header line.""" + name =3D name.strip() + + if not manual: + manual =3D self.manual + + if not modulename: + modulename =3D self.modulename + + self.data +=3D f'.TH "{modulename}" {self.section} "{name}" ' + self.data +=3D f'"{self.date}" "{manual}" LINUX\n' + + def __init__(self, modulename, section=3D"9", manual=3D"API Manual"): """ Creates class variables. =20 @@ -616,7 +629,11 @@ class ManFormat(OutputFormat): """ =20 super().__init__() + self.modulename =3D modulename + self.section =3D section + self.manual =3D manual + self.symbols =3D [] =20 dt =3D None @@ -632,7 +649,7 @@ class ManFormat(OutputFormat): if not dt: dt =3D datetime.now() =20 - self.man_date =3D dt.strftime("%B %Y") + self.date =3D dt.strftime("%B %Y") =20 def arg_name(self, args, name): """ @@ -724,7 +741,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{self.modulename}" 9 "{out_name}" "{self.man= _date}" "API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" @@ -734,7 +751,8 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{name}" 9 "{out_name}" "{self.man_date}" "Ke= rnel Hacker\'s Manual" LINUX' + "\n" + self.emit_th(out_name, modulename =3D name, + manual=3D"Kernel Hacker\'s Manual") =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" @@ -780,7 +798,7 @@ class ManFormat(OutputFormat): def out_enum(self, fname, name, args): out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{self.modulename}" 9 "{out_name}" "{self.man= _date}" "API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"enum {name} \\- {args['purpose']}\n" @@ -813,7 +831,7 @@ class ManFormat(OutputFormat): out_name =3D self.arg_name(args, name) full_proto =3D args.other_stuff["full_proto"] =20 - self.data +=3D f'.TH "{self.modulename}" 9 "{out_name}" "{self.man= _date}" "API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" @@ -834,7 +852,7 @@ class ManFormat(OutputFormat): purpose =3D args.get('purpose') out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{module}" 9 "{out_name}" "{self.man_date}" "= API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"typedef {name} \\- {purpose}\n" @@ -849,7 +867,7 @@ class ManFormat(OutputFormat): definition =3D args.get('definition') out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{module}" 9 "{out_name}" "{self.man_date}" "= API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{args.type} {name} \\- {purpose}\n" --=20 2.52.0 From nobody Thu Apr 9 21:49:32 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 3FFBC3C279F; Thu, 5 Mar 2026 15:16:28 +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=1772723788; cv=none; b=EzFYtnv7YUSqb29tPrHy9vgJCg2cxrj/H5cwqltcEN7JV/BDM/Hz7fQ7FwCmmRqAWFKwxiHwLEtSAcH2lCyGX8qNPJObrMceys8i/XIKx9ElVqdNb+7lnUaurGlXwUoxD+UwuLzliRKdHz83CdUxL5tJlQXvaLwtaUGWfCmvOgg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772723788; c=relaxed/simple; bh=GGvISdxmwoIbUjL//ZMtEtb0uZ7eg3KSR627MLJtNjo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=WLO7AQDwa12VCNFP6EaLMg2Fft0SVFcrOWqvM+h9Tt5GIfmhZ0lvKTLtC7ljN1atmU7hIWaNPyBW/sHlKccjZpGN2ZuYs1AWGbn9OgWMuiWgw9KptmXOZQcrOffAZ9vm202aPN7IIzJRKYJ2tTZBNz6ncEEfys53EW2UWGkFEAo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=flL+4RRu; 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="flL+4RRu" Received: by smtp.kernel.org (Postfix) with ESMTPSA id EA97AC4AF10; Thu, 5 Mar 2026 15:16:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772723788; bh=GGvISdxmwoIbUjL//ZMtEtb0uZ7eg3KSR627MLJtNjo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=flL+4RRuifBoMsCisegVGgimHW1fRtjBQvfPZGcdvE0xqppmCzXUyFbx2JOdoipDW kZuComfLagMUWpqTFuHf6Ubz5XwAFFjLXvOIhcw7m+gCBikw++xusGGZyzgN4YUkjM uiApZaEcgbgJKaWADnbdLFEzL59IiENfFFG7hvJTO2QcgG+1W9mhXy8cOSpsqTmLk4 v6GFSESz6xJkt7CaNH7g+u+wNWX3XFPFvjXx/OoJIr4/z08OeLGjyo2KQX+2Xr80c+ 8WakuQ9CGMx+9RBNs6w2IMxNzRIy916NldnFesiYgj1usf8KVwqiGWt96E428O80ZD jAFoSTbK/Lgbg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyAR8-0000000HK9K-0r8V; Thu, 05 Mar 2026 16:16:26 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH 06/11] docs: kdoc_output: remove extra attribute on man .TH headers Date: Thu, 5 Mar 2026 16:16:13 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab According with modern documents, groff .TH supports up to 5 arguments, but the logic passes 6. Drop the lastest one ("LINUX"). Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index fb6b90c54c8a..d0b237c09391 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -618,7 +618,7 @@ class ManFormat(OutputFormat): modulename =3D self.modulename =20 self.data +=3D f'.TH "{modulename}" {self.section} "{name}" ' - self.data +=3D f'"{self.date}" "{manual}" LINUX\n' + self.data +=3D f'"{self.date}" "{manual}"\n' =20 def __init__(self, modulename, section=3D"9", manual=3D"API Manual"): """ --=20 2.52.0 From nobody Thu Apr 9 21:49:32 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 6C7CD3C3BF8; Thu, 5 Mar 2026 15:16:28 +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=1772723788; cv=none; b=kpvd6e1LjF5tQa9XjqbtDfJ7gvUa5JJbsPKK8wgEo1cXALlE0x8XJppSIlKmmYnAxEp4if0pnKFG8X04tAv79/O0BwH3xjYdaYtYUZIvQMGMuZxPVJYjySAaFBF9U6lIiejScFyfNrfU/2f1wXBKnSAufpHt3IB5vyCTmDfkVH8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772723788; c=relaxed/simple; bh=KClTBbHYRg20aly7xZCzAagKb8bY1y4ys0T0TfWzZRI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=etaED5iWs7X9/OMYkZgWkwrLWltzlXOfhEipRgPSg6EG4IhQFEt3xDpvWw0FqznwAggxaZlhEtUk6i6sg49VkX/mWulxfNO3lm2KU5mHa2aJyW+vvdFlTD0hAEN4Zhk4jI+fYE4UEaisfuh+juX8rbgwAMaCKpTCmkPrzZEriE4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=MJSR0DRX; 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="MJSR0DRX" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4CA13C116C6; Thu, 5 Mar 2026 15:16:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772723788; bh=KClTBbHYRg20aly7xZCzAagKb8bY1y4ys0T0TfWzZRI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=MJSR0DRXLMAyOgBPV38+nGrAMC7yOVUZbNgSFaXGVE2qR8lgRYtREQcXmjFk7TkoC vhDMSy7uHi30wzrR+hb2kOKObHEetLi15NyBUr3BywQLKERREcdMUEHNqimRt9Iv4m lsUNUGoQXaydQnAcDU2xz9q5tqnruPKMsC9EiJJO94yrTDT5j953oVdeAGceUDdNYk /eRfUYxPpmAjzn2/L/Eo7NEsg4LFUywzBvgwA7THI5U97iAvAKnIU7EdjkTEVS0dt/ UJGQ5FgvQTIONe4tvznS+MliJgtKE7aVkrNWYGejicKjhxWfSxl417SgzUy//d9pLt mNJ38NmCGO9MA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyAR8-0000000HKAX-1f1G; Thu, 05 Mar 2026 16:16:26 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH 07/11] docs: kdoc_output: use a single manual for everything Date: Thu, 5 Mar 2026 16:16:14 +0100 Message-ID: <26371b244a4a7aeab9a1e94af87b2e17eb50ff43.1772722474.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab There's no reason why functions will be on a different manual. Unify its name, calling it as "Kernel API Manual". Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index d0b237c09391..24ee1fad681e 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -607,20 +607,17 @@ class ManFormat(OutputFormat): "%m %d %Y", ] =20 - def emit_th(self, name, modulename =3D None, manual=3DNone): + def emit_th(self, name, modulename =3D None): """Emit a title header line.""" name =3D name.strip() =20 - if not manual: - manual =3D self.manual - if not modulename: modulename =3D self.modulename =20 self.data +=3D f'.TH "{modulename}" {self.section} "{name}" ' - self.data +=3D f'"{self.date}" "{manual}"\n' + self.data +=3D f'"{self.date}" "{self.manual}"\n' =20 - def __init__(self, modulename, section=3D"9", manual=3D"API Manual"): + def __init__(self, modulename, section=3D"9", manual=3D"Kernel API Man= ual"): """ Creates class variables. =20 @@ -751,8 +748,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name, modulename =3D name, - manual=3D"Kernel Hacker\'s Manual") + self.emit_th(out_name, modulename =3D name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" --=20 2.52.0 From nobody Thu Apr 9 21:49:32 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 B06CE3C3C0C; Thu, 5 Mar 2026 15:16:28 +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=1772723788; cv=none; b=ZrKXHeRgljZnef6MII26RRYGiA8yIiyDaGqwaasmk2IdlTVAYZsbE2HP5lSJePNB70wwUQS1vS0dSVQe7BZb9K8HnRwoT53AWoGOoqDiqybXcbuo1e+kTdv8BLN9I5ZM3lk+KNW8HKR1nAW8vPGzYJXLJqE6353MeO38oDx7XiM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772723788; c=relaxed/simple; bh=P85ihOR34EEBJ4aigkm1P5PoviijGjWWN5/y18JiWZo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ppZVjBtun1+Wxd8Pcq5W7j5nTPq+6QMqOfpTjbD5KqvgPFZBd0Htk73h7S9DZDSVrqbx5ZOR+KfTAbycIHPKI6XMcTV+oRu+PMdH8l/5BL+Bq6YY3DQSVUVEJPwM7gewFzCDwjlbVmH+Si45t9ZAd37lHOZeXK7dhLBwvCr2hzI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=UoI/y0Ow; 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="UoI/y0Ow" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 7E083C19423; Thu, 5 Mar 2026 15:16:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772723788; bh=P85ihOR34EEBJ4aigkm1P5PoviijGjWWN5/y18JiWZo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=UoI/y0OwuOStGlQOB/mn3B75ViUp3uyuMesvL51nPEhU6ZMoFqBWxHkXZUcwtRmJi lG6ZGIbiOgonfRO5djeVCsvaV0TTgnJh+/k51RG1U1KJvQrGN0RZYhQU2yL6U0TPg9 u82kHnaO4cJ8Km0tnDgHfG+3Ep9C+0l2oJItaUaj+JdwNxWsQj5NkdPikiHJ3tzvfv UwQVYBpDaHh+M+m/ZGHmhZZkp7b2lkvLu8ju91XcgK0AGcGPxGG0F4lPfXSOFqRpOK ZleEsG81DCosS+ML3+1Ig6qCpP+RSWZLp4xyHdozvtJm8Ygb6oeqcTvWkvspVdPDxo F7PhamdB/1T7g== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyAR8-0000000HKBk-2UJX; Thu, 05 Mar 2026 16:16:26 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH 08/11] docs: kdoc_output: don't use a different modulename for functions Date: Thu, 5 Mar 2026 16:16:15 +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 It doesn't make much sense to have a different modulename just for functions, but not for structs/enums/... Use the same header everywere. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 24ee1fad681e..62e300e65405 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -607,14 +607,11 @@ class ManFormat(OutputFormat): "%m %d %Y", ] =20 - def emit_th(self, name, modulename =3D None): + def emit_th(self, name): """Emit a title header line.""" name =3D name.strip() =20 - if not modulename: - modulename =3D self.modulename - - self.data +=3D f'.TH "{modulename}" {self.section} "{name}" ' + self.data +=3D f'.TH "{self.modulename}" {self.section} "{name}" ' self.data +=3D f'"{self.date}" "{self.manual}"\n' =20 def __init__(self, modulename, section=3D"9", manual=3D"Kernel API Man= ual"): @@ -748,7 +745,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name, modulename =3D name) + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" --=20 2.52.0 From nobody Thu Apr 9 21:49:32 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 C65E33C3C11; Thu, 5 Mar 2026 15:16:28 +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=1772723788; cv=none; b=mLRdJiW/ulvVIpVTDS83ri8AuAf4GjGqEK4Iwa63kMXL4SJs6Uz4arkL3ZzegC/NtFMaC5l1PQVkz3v/ccLDZK5gPiZrwl4saQy2d0YlT4Qaugm67HpfBBc7xfiuHie5VC3LcB5UyrgZynaS56b8p7Zgjm4yJviEZt8+p+iT/7U= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772723788; c=relaxed/simple; bh=1bL9ZrKbJcLEeJVsYJFtpZiURmsITtjUamQCEe8R0Hc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=OtLmV0Jy9WvNzeRcj9K5qiUHEN7gnGwnAkkmSrRHV2ZbXFrsnLEoUP4GtdMEMrE8YSq4eRf+w5LZQSlfFvsWFj46k6x8EqXdAn2LL7Y/tFfqeAPIlscYgRvnGQ75QbfenSC7Vl/7ki6xrf4aH6fGhvTiVNtlKPgp7WrsHjhT5tY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Gs3xH7Iy; 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="Gs3xH7Iy" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A1683C116C6; Thu, 5 Mar 2026 15:16:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772723788; bh=1bL9ZrKbJcLEeJVsYJFtpZiURmsITtjUamQCEe8R0Hc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Gs3xH7IyVGIeOHCVlZUqHY4gy2Cs5HTweK5QO3kekarJG23n9QAYcbDCoh+yCdEGZ Ez5DDzHeAyIQdNKgpSWwIDMWP8k0+87ZACH+8btJhBn3yLH77o5nTzb0FCUYjYm+JC +4izAYpw4Xk2nrJ2ryP9Op4zHDMLzHjzO9hYJ8vzN1qV6spu4512q5yjK983yqZp4E KUu16oBb25CNg42PsfcYk4DURzF/SivLzBhFvIsYzsdahIj2X3BFrJUu1y6lTFhjfS 0ZK0/k6fdUn8bD8ScR9kmK7kkLnlsFfecBK4/Yglip8Bff9Fk4JidNvoGczX7BgxKl aeT4gE5rCvuAA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyAR8-0000000HKCy-3IVF; Thu, 05 Mar 2026 16:16:26 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Shuah Khan Subject: [PATCH 09/11] docs: kdoc_output: use a more standard order for .TH on man pages Date: Thu, 5 Mar 2026 16:16:16 +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 The generated man pages are not following the current standards for Linux documentation. Reorder .TH fields for them to look like other Linux man pages. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/sphinx-build-wrapper | 2 +- tools/lib/python/kdoc/kdoc_output.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index 4572328e379d..3b3b8dd074a8 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -626,7 +626,7 @@ class SphinxBuilder: # Use shlex here, as it handles well parameters with commas args =3D shlex.split(line) name =3D args[1].replace("/", " ") - fname =3D f"{output_dir}/{args[3]}.{args[2]}" + fname =3D f"{output_dir}/{args[1]}.{args[2]}" =20 if self.verbose: print(f"Creating {fname}") diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 62e300e65405..968e1d43de47 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -611,8 +611,8 @@ class ManFormat(OutputFormat): """Emit a title header line.""" name =3D name.strip() =20 - self.data +=3D f'.TH "{self.modulename}" {self.section} "{name}" ' - self.data +=3D f'"{self.date}" "{self.manual}"\n' + self.data +=3D f'.TH "{name}" {self.section} "{self.date}" ' + self.data +=3D f'"{self.modulename}" "{self.manual}"\n' =20 def __init__(self, modulename, section=3D"9", manual=3D"Kernel API Man= ual"): """ --=20 2.52.0 From nobody Thu Apr 9 21:49:32 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 00D693C6A23; Thu, 5 Mar 2026 15:16:29 +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=1772723789; cv=none; b=QIhoKVWt+ghHB6I5chYwH3crBybfBa9O3vMqxs9N4fQl3i3LcQfoDxV/hIcn6GGLGF7m0EBUnKycSQv7IS9bYc1hcpO1VlrDbQ39KaBtR/qaWMobFhMbGm91Hp9GEM0aTwLjAG+DCRkEHD1sQTGXQ3fsbc1WbfHTKnMZAeoWAkg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772723789; c=relaxed/simple; bh=ZNZ2mFKPm+G9plRvw4WRwSksYn8HB30/8SoYLAYS4yM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=c9NHC+/DyT8OA0F126cswSsB7DM51FmTKrUcIbi/SAen2oqjODIcPWaZenXdoDwcDSVkGT3P8G1Jr7tkuMOm09Ce6TWuZjKcZE04IwCZxtHB8dFKBuypJZwpf6rymCl026uEIZMJyVxCPHhHZRwIbQQMlQa6m0J9cJ47PbHwb5M= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ZROBnyn8; 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="ZROBnyn8" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D470CC2BC87; Thu, 5 Mar 2026 15:16:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772723788; bh=ZNZ2mFKPm+G9plRvw4WRwSksYn8HB30/8SoYLAYS4yM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZROBnyn8LoKoDWsT8Q590A8E2tRzecZaRoov4PaRwU92zao694dz2OzST1Ay20p3P yeN73l7B3rsiwrK4TvgXwbXpY87HRX31hitS63+5zSFiIJJCnLL/PonneMIGiK5/mw exhipSzx6YR4xIRRq5AOod+cT/y+30AvAeLzNZrliMHzNbmdHoAWV+Fs7UY9kCSkDP y5Co/7A0H2SY6MHl4r2cT3Z3ipNa7wpwbLRE9YN/aEf2l7fVuQepmx+RY0PG1FrLFA IHXvCXWi62IXUeHHmfwQnAdUYvzWJ7TtodW1hJ64aHoQQ9aXfZn282IEa86fhF1jx+ yfb7mP/o2Lv3w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyAR8-0000000HKEB-46YB; Thu, 05 Mar 2026 16:16:26 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH 10/11] docs: kdoc_output: describe the class init parameters Date: Thu, 5 Mar 2026 16:16:17 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab As this class is part of the ABI used by both Sphinx kerneldoc extension and docs/tools/kernel-doc, better describe what parmeters are used to initialize ManOutput class. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 29 +++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 968e1d43de47..52fc41bd17b7 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -580,7 +580,34 @@ class RestFormat(OutputFormat): =20 =20 class ManFormat(OutputFormat): - """Consts and functions used by man pages output.""" + """ + Consts and functions used by man pages output. + + This class has one mandatory parameter and some optional ones, which + are needed to define the title header contents: + + ``modulename`` + Defines the module name to be used at the troff ``.TH`` output. + + This argument is mandatory. + + ``section`` + Usually a numeric value from 0 to 9, but man pages also accept + some strings like "p". + + Defauls to ``9`` + + ``manual`` + Defaults to ``Kernel API Manual``. + + The above controls the output of teh corresponding fields on troff + title headers, which will be filled like this:: + + .TH "{name}" {section} "{date}" "{modulename}" "{manual}" + + where ``name``` will match the API symbol name, and ``date`` will be + either the date where the Kernel was compiled or the current date + """ =20 highlights =3D ( (type_constant, r"\1"), --=20 2.52.0 From nobody Thu Apr 9 21:49:32 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 31F983C6A2E; Thu, 5 Mar 2026 15:16:29 +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=1772723789; cv=none; b=mTjERiJ/zwVbDI8exNE1OWKZvHOJjD2IBSx0xpaTXOvgfKnFKcDTVQNMLf8ma0qJUO0xgFUbCKK4GMuZJ1XftDig5n8Zucyvu94F+hF8FOHQLOKDdlK0WaO/K5D/p8oQmjTZTuM/o6jqSZLh2XIauE7IvbVwemBfGi09bPudTOk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772723789; c=relaxed/simple; bh=KRhaVj36QPpFVRt1j0+gEDFYVEUP/qyFJd2IndbJHfA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=XNzl1lson5pPTNMNlNdF68a3RIK6Tq+c3iKW9YwJgcESXAS25Ub0XU40PiZjrw4DZdfOU2EQRsGg0JBXR2PvsYswHsZbFmzNrCUUG1hakGb28qUtZjq7UvpRLwFPEKt/MTNZwa196p/7she3yEEoeXPRJ2DFD3aDwUX3s2Yba7k= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=kSFIuG7I; 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="kSFIuG7I" Received: by smtp.kernel.org (Postfix) with ESMTPSA id DB3BCC19423; Thu, 5 Mar 2026 15:16:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772723788; bh=KRhaVj36QPpFVRt1j0+gEDFYVEUP/qyFJd2IndbJHfA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=kSFIuG7IZonQGHHdPJDQwAjl54WLr6jkqE/S3GQf/C1Ze62oUQeu0hDwPSdhHTJqn oRl2DoKqSJiOAInkCUnAeqQyOHygMU09nxb5nkHkjsuGf+xwPhXkA5QN2eRIqUXdOx TSEA7zNqo9sslNsI7OkIOOJfV6nWDWdE9RuE4RVfuNklaDagQ5Hq1vUbBcPwgNhMx4 9PHcxZWYS06uuUVOqm/QbXZn2gQtlXyEnuKUm5DMSRPjwTsF0QNAw2OF/964U4CHqv JKNRkzjGzB1Y9v8zY/EoMrblnMwg3o51tWSkvln1g8vjfNsbvomCacPXtgW6GzBxQm Sca8Lr63JvzAw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyAR9-0000000HKFO-0jdT; Thu, 05 Mar 2026 16:16:27 +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 11/11] docs: kdoc_output: pick a better default for modulename Date: Thu, 5 Mar 2026 16:16:18 +0100 Message-ID: <651be6529cd926802cc555840595421dbb158ab8.1772722474.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 placing the same data for modulename for all generated man pages, use the directory from the filename used to produce kernel docs as basis. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/kernel-doc | 1 - tools/lib/python/kdoc/kdoc_output.py | 41 +++++++++++++++++----------- 2 files changed, 25 insertions(+), 17 deletions(-) diff --git a/tools/docs/kernel-doc b/tools/docs/kernel-doc index aed09f9a54dd..3a932f95bdf5 100755 --- a/tools/docs/kernel-doc +++ b/tools/docs/kernel-doc @@ -210,7 +210,6 @@ def main(): help=3D"Enable debug messages") =20 parser.add_argument("-M", "-modulename", "--modulename", - default=3D"Kernel API", help=3D"Allow setting a module name at the output.= ") =20 parser.add_argument("-l", "-enable-lineno", "--enable_lineno", diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 52fc41bd17b7..8d415b79b6f9 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -589,7 +589,8 @@ class ManFormat(OutputFormat): ``modulename`` Defines the module name to be used at the troff ``.TH`` output. =20 - This argument is mandatory. + This argument is optional. If not specified, it will be filled + with the directory which contains the documented file. =20 ``section`` Usually a numeric value from 0 to 9, but man pages also accept @@ -634,14 +635,21 @@ class ManFormat(OutputFormat): "%m %d %Y", ] =20 - def emit_th(self, name): + def emit_th(self, name, args): """Emit a title header line.""" - name =3D name.strip() + title =3D name.strip() + module =3D self.modulename(args) =20 - self.data +=3D f'.TH "{name}" {self.section} "{self.date}" ' - self.data +=3D f'"{self.modulename}" "{self.manual}"\n' + self.data +=3D f'.TH "{title}" {self.section} "{self.date}" ' + self.data +=3D f'"{module}" "{self.manual}"\n' =20 - def __init__(self, modulename, section=3D"9", manual=3D"Kernel API Man= ual"): + def modulename(self, args): + if self._modulename: + return self._modulename + + return os.path.dirname(args.fname) + + def __init__(self, modulename=3DNone, section=3D"9", manual=3D"Kernel = API Manual"): """ Creates class variables. =20 @@ -651,7 +659,7 @@ class ManFormat(OutputFormat): =20 super().__init__() =20 - self.modulename =3D modulename + self._modulename =3D modulename self.section =3D section self.manual =3D manual =20 @@ -685,7 +693,8 @@ class ManFormat(OutputFormat): dtype =3D args.type =20 if dtype =3D=3D "doc": - return self.modulename + return name +# return os.path.basename(self.modulename(args)) =20 if dtype in ["function", "typedef"]: return name @@ -762,7 +771,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" @@ -772,7 +781,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" @@ -818,7 +827,7 @@ class ManFormat(OutputFormat): def out_enum(self, fname, name, args): out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"enum {name} \\- {args['purpose']}\n" @@ -851,7 +860,7 @@ class ManFormat(OutputFormat): out_name =3D self.arg_name(args, name) full_proto =3D args.other_stuff["full_proto"] =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" @@ -868,11 +877,11 @@ class ManFormat(OutputFormat): self.output_highlight(text) =20 def out_typedef(self, fname, name, args): - module =3D self.modulename + module =3D self.modulename(args) purpose =3D args.get('purpose') out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"typedef {name} \\- {purpose}\n" @@ -882,12 +891,12 @@ class ManFormat(OutputFormat): self.output_highlight(text) =20 def out_struct(self, fname, name, args): - module =3D self.modulename + module =3D self.modulename(args) purpose =3D args.get('purpose') definition =3D args.get('definition') out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{args.type} {name} \\- {purpose}\n" --=20 2.52.0