From nobody Fri Dec 19 20:32:39 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 108AF1E8347; Wed, 19 Feb 2025 13:57:59 +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=1739973480; cv=none; b=GA6oW7B2Afwgar3a3D8vpwdCkEenhjqlgGggA4Anh6+GkkMXgk2pEWna1Ncz/+imHSDXRCE9sQA3pkQ2vmUHV758uuATZKuXT1/3r3RBJu1//OKj6vs2kZQoWiVznL2ZngDHG3qTZf56VBL1AeByXbRgdPVplwX+yOzbqFUG8wg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739973480; c=relaxed/simple; bh=RPy+c9M9XnSF7fnvH42jTZeZw448FaaVZdh7+FOlT+M=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=K8rAe14WjcxPaiZ07CzXxOkaWmhELZw4aAr/IKFdPMeg0e0XoNykqst34Oy2t7jsNmG/9D8WgdmzDp0pAqUas6Yz1B0EqTERFNO99PROOCRD2Q5hK5Uq3ck5xIq2ChLbL1b7nC6mEPSKOADepE9smELrOFHSNlPnx68h9iTE2ig= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=SPQ6QDDo; 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="SPQ6QDDo" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 94AE9C4CEE0; Wed, 19 Feb 2025 13:57:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1739973479; bh=RPy+c9M9XnSF7fnvH42jTZeZw448FaaVZdh7+FOlT+M=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=SPQ6QDDoZ4F1MXQEUy+Z+h7yDNVxu5v2g/DwNCiQRC7YwmbivCptds62RpRUt/JZc PaO4rASQMvfsLoKX5babgf2we+TfomBqsuKmne/dgOzvT5yPICoM17FLMOt+M9J4Lj 20ayGoQMOHsbl2p24vgwkP0HnNM3v7lo5cZeiqYz2h0wg4b60cfBezn0ebCOnDWmLy UzXq0zjpxHUEFXXIk93N7JhDxkpI/u1eLEqWijsXHyjX+2uw36cEXZTKRH8oEkvhPy Ke+ME7zAttBxFjyDSzq3ma36/nCD6HUSPXj35OG1z/WPP/VfJT29949cg+wdLbWvrC IOAXbQcpkkVQA== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tkkaL-0000000H1jF-0Zk9; Wed, 19 Feb 2025 14:57:57 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH 1/6] scripts/kernel-doc.py: Set an output format for --none Date: Wed, 19 Feb 2025 14:57:36 +0100 Message-ID: <465a4660df470b214aec6abe1b2b931781ef2122.1739972906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Now that warnings output is deferred to the output plugin, we need to have an output style for none as well. So, use the OutputFormat base class on such cases. Signed-off-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_files.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py index c215ae3047b8..957aaeaed7e6 100755 --- a/scripts/lib/kdoc/kdoc_files.py +++ b/scripts/lib/kdoc/kdoc_files.py @@ -19,6 +19,7 @@ from datetime import datetime from dateutil import tz =20 from kdoc_parser import KernelDoc +from kdoc_output import OutputFormat =20 =20 class GlobSourceFiles: @@ -137,6 +138,9 @@ class KernelFiles(): if not modulename: modulename =3D "Kernel API" =20 + if out_style is None: + out_style =3D OutputFormat() + dt =3D datetime.now() if os.environ.get("KBUILD_BUILD_TIMESTAMP", None): # use UTC TZ --=20 2.48.1 From nobody Fri Dec 19 20:32:39 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 109041EA7C6; Wed, 19 Feb 2025 13:57:59 +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=1739973480; cv=none; b=pOI5E+WV2vHCQJxvV89xCxK8853W8f7n01iP4qOHhsE14fHz0c0tCeysemndcj4tYIQiJTlHg4DXp7Q2RJHjxpGOCrJ6+2PEqqJms9MrXAj1Mz20I+W9mA203IxkNyqS59UGIGum4az5faDvh8QHl2YT5ppWVyW1E/cz5f6Nj+Y= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739973480; c=relaxed/simple; bh=6Zn2EKfxJ7Vkt0h37tV3CPuGsXDQh4z4UJHEkZnGtBU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=sXhTL2P+rm1mpxezFumHAH/9vlo8l6ngxCLYROw/5rs7fYUW87G/dCwvEoRdf2T0dlA8Cu2pjVSKQJi5B2cGhYZHMEp3ZJz8zKcIhH+IPJsah8TENm9lQvV1RBw9Wy5MyhgRdzhLDasz5x+itrd0r777CTdb6N46fXFlRIbrNP4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=DgDFeI/O; 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="DgDFeI/O" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9B7B6C4CEDD; Wed, 19 Feb 2025 13:57:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1739973479; bh=6Zn2EKfxJ7Vkt0h37tV3CPuGsXDQh4z4UJHEkZnGtBU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=DgDFeI/O2NNbrkNTZzx7DETQlfdJh1O6gY8v1fE6wo/efX3cuwikAt4W0MF8rfjLV nQ5vbJp61d/b8mj32OVIfXlPfaf/a7UdfJEOC3szOJH5sL3EgaFlFBVIyGwg7v9klx /l+pmKWiDscEUcMO5sx6PLbLHQNzWyae3n7AAuMZQHEEdVct02UvZQP5WRCkNgOql4 9/+p0r8mwGDXj2SGqPyIqt6K0yp31wxmzMSPrUl/QJB/94MH3L3uUrzKMZJVIoBbZx WCNjotpdseScoPY1xwYmgl/ffAdDVSq5nNbdb0UnZ3BactZhPJJRMW3xHQj+InomvL qQTqBiN/jQpHw== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tkkaL-0000000H1jJ-0gi4; Wed, 19 Feb 2025 14:57:57 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH 2/6] scripts/kernel-doc.py: adjust some coding style issues Date: Wed, 19 Feb 2025 14:57:37 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Make pylint happier by adding some missing documentation and addressing a couple of pylint warnings. Signed-off-by: Mauro Carvalho Chehab --- scripts/kernel-doc.py | 2 ++ scripts/lib/kdoc/kdoc_files.py | 4 +-- scripts/lib/kdoc/kdoc_output.py | 51 ++++++++++++++++++++++++++------- 3 files changed, 43 insertions(+), 14 deletions(-) diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py index d700451e9541..daae2b4f3307 100755 --- a/scripts/kernel-doc.py +++ b/scripts/kernel-doc.py @@ -90,6 +90,8 @@ neither here nor at the original Perl script. =20 =20 class MsgFormatter(logging.Formatter): + """Helper class to format warnings on a similar way to kernel-doc.pl""" + def format(self, record): record.levelname =3D record.levelname.capitalize() return logging.Formatter.format(self, record) diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py index 957aaeaed7e6..e1ed2f6dae94 100755 --- a/scripts/lib/kdoc/kdoc_files.py +++ b/scripts/lib/kdoc/kdoc_files.py @@ -3,8 +3,6 @@ # Copyright(c) 2025: Mauro Carvalho Chehab . # SPDX-License-Identifier: GPL-2.0 =20 -# TODO: implement warning filtering - """ Parse lernel-doc tags on multiple kernel source files. """ @@ -127,7 +125,7 @@ class KernelFiles(): def __init__(self, verbose=3DFalse, out_style=3DNone, werror=3DFalse, wreturn=3DFalse, wshort_desc=3DFalse, wcontents_before_sections=3DFalse, - logger=3DNone, modulename=3DNone, export_file=3DNone): + logger=3DNone, modulename=3DNone): """ Initialize startup variables and parse all files """ diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index 7aeaec884545..97ec671e0b6e 100755 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -1,10 +1,8 @@ #!/usr/bin/env python3 -# pylint: disable=3DC0301,R0911,R0912,R0913,R0914,R0915,R0917 +# pylint: disable=3DC0301,R0902,R0911,R0912,R0913,R0914,R0915,R0917 # Copyright(c) 2025: Mauro Carvalho Chehab . # SPDX-License-Identifier: GPL-2.0 =20 -# TODO: implement warning filtering - """ Implement output filters to print kernel-doc documentation. =20 @@ -51,6 +49,11 @@ type_member_func =3D type_member + Re(r"\(\)", cache=3DF= alse) =20 =20 class OutputFormat: + """ + Base class for OutputFormat. If used as-is, it means that only + warnings will be displayed. + """ + # output mode. OUTPUT_ALL =3D 0 # output all symbols and doc sections OUTPUT_INCLUDE =3D 1 # output only specified symbols @@ -74,6 +77,10 @@ class OutputFormat: self.data =3D "" =20 def set_config(self, config): + """ + Setup global config variables used by both parser and output. + """ + self.config =3D config =20 def set_filter(self, export, internal, symbol, nosymbol, function_tabl= e, @@ -116,6 +123,10 @@ class OutputFormat: return block =20 def out_warnings(self, args): + """ + Output warnings for identifiers that will be displayed. + """ + warnings =3D args.get('warnings', []) =20 for warning, log_msg in warnings: @@ -145,6 +156,11 @@ class OutputFormat: return False =20 def check_declaration(self, dtype, name, args): + """ + Checks if a declaration should be output or not based on the + filtering criteria. + """ + if name in self.nosymbol: return False =20 @@ -168,6 +184,10 @@ class OutputFormat: return False =20 def msg(self, fname, name, args): + """ + Handles a single entry from kernel-doc parser + """ + self.data =3D "" =20 dtype =3D args.get('type', "") @@ -202,24 +222,24 @@ class OutputFormat: return None =20 # Virtual methods to be overridden by inherited classes + # At the base class, those do nothing. def out_doc(self, fname, name, args): - pass + """Outputs a DOC block""" =20 def out_function(self, fname, name, args): - pass + """Outputs a function""" =20 def out_enum(self, fname, name, args): - pass + """Outputs an enum""" =20 def out_typedef(self, fname, name, args): - pass + """Outputs a typedef""" =20 def out_struct(self, fname, name, args): - pass - + """Outputs a struct""" =20 class RestFormat(OutputFormat): - # """Consts and functions used by ReST output""" + """Consts and functions used by ReST output""" =20 highlights =3D [ (type_constant, r"``\1``"), @@ -264,6 +284,11 @@ class RestFormat(OutputFormat): self.data +=3D f".. LINENO {ln}\n" =20 def output_highlight(self, args): + """ + Outputs a C symbol that may require being converted to ReST using + the self.highlights variable + """ + input_text =3D args output =3D "" in_literal =3D False @@ -578,6 +603,10 @@ class ManFormat(OutputFormat): self.man_date =3D dt.strftime("%B %Y") =20 def output_highlight(self, block): + """ + Outputs a C symbol that may require being highlighted with + self.highlights variable using troff syntax + """ =20 contents =3D self.highlight_block(block) =20 @@ -600,7 +629,7 @@ class ManFormat(OutputFormat): sections =3D args.get('sections', {}) =20 if not self.check_doc(name, args): - return + return =20 self.data +=3D f'.TH "{module}" 9 "{module}" "{self.man_date}" "AP= I Manual" LINUX' + "\n" =20 --=20 2.48.1 From nobody Fri Dec 19 20:32:39 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C3CA01DEFE1; Wed, 19 Feb 2025 13:57:59 +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=1739973479; cv=none; b=E7bJrqUNI0BUq9dN42jhRMmK/ce1MbYPq6cpSlSJ2i/Pb1IUribqCnBxkqgV4PDPEMcVAoBSoRs/ZfZw6QR/LRY35uZrmlu7boHFGSK18ablPVd4rvwBANkcGtKENjdoqbcpl3V5GShDW8JLezJgT+977mwatCbCZl2wXDAo0Yw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739973479; c=relaxed/simple; bh=cgbg7nED/bJ/uBnZ2iDb/1x2SRXvvmDXvNCZuMR+Pis=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Z7S6EEN16/GnGFvVwiqx98xLGkIm1cyCw4e5z6Xb/aBRT9IlAYtgRrsqMFUd38mXGN+q4lOg37/5PVQnB6ZkJwedaT1F45QKftcmvW2rkegeBIR7eA5U24sm4ickuhuSD5aumY0ERRWH2MlGlCtaKHhhJC31Pa1cPX4z0eXZAuQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ukUbGMKm; 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="ukUbGMKm" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 96FFEC4CEE7; Wed, 19 Feb 2025 13:57:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1739973479; bh=cgbg7nED/bJ/uBnZ2iDb/1x2SRXvvmDXvNCZuMR+Pis=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ukUbGMKmoQcbgWLlfZhrWNaW54CJCQmzdWBqPVrzk07C0RCcVxU6OXm4/FkE4sw5S 8mS+Xsf/tLj+0HiBp8lGd8jQZRRZuzunpefYNgXo7jb50CEZ8oLO2ZpYVxMbGXU6RK 6iPZ3vd/U3Km3UOOhq2hMa+cyNU5mveXSIypcXAHC+iEd+YODc30kvFFyGQkbRCRbn ZCYgjgxdgrH380UDwuMt16VkLJVypLM2vQ+/4OSMY6B+hQgooHX6/UcjqGPNIwrCY7 AVgQxA9gHQa3pbny3mvw29aBdzbO+Rot17rVu/EADvjI9b3wW+pOPcT4pRcYGXjZ3X lbEgbHvo891tQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tkkaL-0000000H1jN-0njG; Wed, 19 Feb 2025 14:57:57 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH 3/6] scripts/lib/kdoc/kdoc_parser.py: fix Python compat with < v3.13 Date: Wed, 19 Feb 2025 14:57:38 +0100 Message-ID: <34593958dab76d805b388bda8d10737cfecb7845.1739972906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" - str.replace count was introduced only in Python 3.13; - before Python 3.13, f-string dict arguments can't use the same delimiter of the main string. Signed-off-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_output.py | 8 ++++---- scripts/lib/kdoc/kdoc_parser.py | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index 97ec671e0b6e..df3c15bb1c10 100755 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -645,16 +645,16 @@ class ManFormat(OutputFormat): sectionlist =3D args.get('sectionlist', []) sections =3D args.get('sections', {}) =20 - self.data +=3D f'.TH "{args['function']}" 9 "{args['function']}" "= {self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n" + self.data +=3D f'.TH "{args["function"]}" 9 "{args["function"]}" "= {self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n" =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{args['function']} \\- {args['purpose']}\n" =20 self.data +=3D ".SH SYNOPSIS\n" if args.get('functiontype', ''): - self.data +=3D f'.B "{args['functiontype']}" {args['function']= }' + "\n" + self.data +=3D f'.B "{args["functiontype"]}" {args["function"]= }' + "\n" else: - self.data +=3D f'.B "{args['function']}' + "\n" + self.data +=3D f'.B "{args["function"]}' + "\n" =20 count =3D 0 parenth =3D "(" @@ -695,7 +695,7 @@ class ManFormat(OutputFormat): sectionlist =3D args.get('sectionlist', []) sections =3D args.get('sections', {}) =20 - self.data +=3D f'.TH "{args['module']}" 9 "enum {args['enum']}" "{= self.man_date}" "API Manual" LINUX' + "\n" + self.data +=3D f'.TH "{args["module"]}" 9 "enum {args["enum"]}" "{= self.man_date}" "API Manual" LINUX' + "\n" =20 self.data +=3D ".SH NAME\n" self.data +=3D f"enum {args['enum']} \\- {args['purpose']}\n" diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index a71145d531f2..51ac2d69a587 100755 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1455,9 +1455,9 @@ class KernelDoc: =20 r =3D Re(r'long\s+(sys_.*?),') if r.search(proto): - proto =3D proto.replace(',', '(', count=3D1) + proto =3D Re(',').sub('(', proto, count=3D1) elif is_void: - proto =3D proto.replace(')', '(void)', count=3D1) + proto =3D Re(r'\)').sub('(void)', proto, count=3D1) =20 # Now delete all of the odd-numbered commas in the proto # so that argument types & names don't have a comma between them --=20 2.48.1 From nobody Fri Dec 19 20:32:39 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 2E2EE1EA7F0; Wed, 19 Feb 2025 13:57:59 +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=1739973480; cv=none; b=Pw8ex1qvoRY40BIZ21F5d5NDVOKogHLQAToC6gTC0yA6wwpcX2ntYxNSj1BDKNk7qMdhaHqFbSLMEolWpU0+Fs5AtF89avTG2GK4OMB3+Ijf8hwI0q40TF5sYs8FyOyri3LLu6EFFKww3IQWO64i2OkvHWbWvN+CCKBMOXLDB1g= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739973480; c=relaxed/simple; bh=4i9tMFsRvYQf8CGO56ooCSwnWGYo0A/a2tTzIVmQWtE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Y2eMOxYwiOHKTYbHigCTin20E8ZnJaR35QgSJavhf90R9LfFf5E1k2QGohgNPvJjfDVX1K7W644CawyoD8cmCkLJbtm7ZRHyILgTcEQn0ojKkHJL2F/SbevL+vrhKAT2iD74Q5IKigPd+82u9hFStRQ/N0vgCnxgx6KcPUUs6Fc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=htesH/wF; 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="htesH/wF" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 90750C4CED1; Wed, 19 Feb 2025 13:57:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1739973479; bh=4i9tMFsRvYQf8CGO56ooCSwnWGYo0A/a2tTzIVmQWtE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=htesH/wFcMgCM7lbllXD5H23KE4fKWmk4hgZgcto/aU4FTsHZIr3eKaJ4CJYwbXrc 1H1uqv47+ZIXWW9F6htG4p07ARQ5GdMzFH4nO1l9D8TWi1n6ooK4wO5m4NXMZnwz3s v8Qk7TzMqe5Y1+op+6rLH5S4FyyVnH5K2Feb3cCfAMjGU2m9qvHFMtImyh/hSALKD5 oq3vEKFkfOZ7lAnE7+e2F/F4TSFh58NkOKLuVCXhiigsZQuUEv0OA7JNJjZEGnpt0m wW50EVQYnB3/G5qL02PlBhfoibNeS9DK4+kTF3A9LZk3g1EJ5uN7UaM/0sNsX9iURx jMmd4qmh8CKiw== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tkkaL-0000000H1jR-0uVR; Wed, 19 Feb 2025 14:57:57 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH 4/6] scripts/kernel-doc.py: move modulename to man class Date: Wed, 19 Feb 2025 14:57:39 +0100 Message-ID: <138c24649a378ff5ff5fd6c05dfc1cf83e21bc07.1739972906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Only man output requires a modulename. Move its definition to the man class. Signed-off-by: Mauro Carvalho Chehab --- scripts/kernel-doc.py | 6 +++--- scripts/lib/kdoc/kdoc_files.py | 6 +----- scripts/lib/kdoc/kdoc_output.py | 12 ++++++------ scripts/lib/kdoc/kdoc_parser.py | 9 +-------- 4 files changed, 11 insertions(+), 22 deletions(-) diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py index daae2b4f3307..064106c18d8b 100755 --- a/scripts/kernel-doc.py +++ b/scripts/kernel-doc.py @@ -111,6 +111,7 @@ 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", @@ -198,7 +199,7 @@ def main(): logger.addHandler(handler) =20 if args.man: - out_style =3D ManFormat() + out_style =3D ManFormat(modulename=3Dargs.modulename) elif args.none: out_style =3D None else: @@ -207,8 +208,7 @@ def main(): kfiles =3D KernelFiles(verbose=3Dargs.verbose, out_style=3Dout_style, werror=3Dargs.werror, wreturn=3Dargs.wreturn, wshort_desc=3Dargs.wshort= _desc, - wcontents_before_sections=3Dargs.wcontents_before= _sections, - modulename=3Dargs.modulename) + wcontents_before_sections=3Dargs.wcontents_before= _sections) =20 kfiles.parse(args.files, export_file=3Dargs.export_file) =20 diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py index e1ed2f6dae94..a2417cafb1c8 100755 --- a/scripts/lib/kdoc/kdoc_files.py +++ b/scripts/lib/kdoc/kdoc_files.py @@ -125,7 +125,7 @@ class KernelFiles(): def __init__(self, verbose=3DFalse, out_style=3DNone, werror=3DFalse, wreturn=3DFalse, wshort_desc=3DFalse, wcontents_before_sections=3DFalse, - logger=3DNone, modulename=3DNone): + logger=3DNone): """ Initialize startup variables and parse all files """ @@ -133,9 +133,6 @@ class KernelFiles(): if not verbose: verbose =3D bool(os.environ.get("KBUILD_VERBOSE", 0)) =20 - if not modulename: - modulename =3D "Kernel API" - if out_style is None: out_style =3D OutputFormat() =20 @@ -167,7 +164,6 @@ class KernelFiles(): self.config.wreturn =3D wreturn self.config.wshort_desc =3D wshort_desc self.config.wcontents_before_sections =3D wcontents_before_sections - self.config.modulename =3D modulename =20 self.config.function_table =3D set() self.config.source_map =3D {} diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index df3c15bb1c10..13a74a687f89 100755 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -584,7 +584,7 @@ class ManFormat(OutputFormat): ) blankline =3D "" =20 - def __init__(self): + def __init__(self, modulename): """ Creates class variables. =20 @@ -593,6 +593,7 @@ class ManFormat(OutputFormat): """ =20 super().__init__() + self.modulename =3D modulename =20 dt =3D datetime.now() if os.environ.get("KBUILD_BUILD_TIMESTAMP", None): @@ -624,14 +625,13 @@ class ManFormat(OutputFormat): self.data +=3D line + "\n" =20 def out_doc(self, fname, name, args): - module =3D args.get('module') sectionlist =3D args.get('sectionlist', []) sections =3D args.get('sections', {}) =20 if not self.check_doc(name, args): return =20 - self.data +=3D f'.TH "{module}" 9 "{module}" "{self.man_date}" "AP= I Manual" LINUX' + "\n" + self.data +=3D f'.TH "{self.modulename}" 9 "{self.modulename}" "{s= elf.man_date}" "API Manual" LINUX' + "\n" =20 for section in sectionlist: self.data +=3D f'.SH "{section}"' + "\n" @@ -695,7 +695,7 @@ class ManFormat(OutputFormat): sectionlist =3D args.get('sectionlist', []) sections =3D args.get('sections', {}) =20 - self.data +=3D f'.TH "{args["module"]}" 9 "enum {args["enum"]}" "{= self.man_date}" "API Manual" LINUX' + "\n" + self.data +=3D f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "= {self.man_date}" "API Manual" LINUX' + "\n" =20 self.data +=3D ".SH NAME\n" self.data +=3D f"enum {args['enum']} \\- {args['purpose']}\n" @@ -725,7 +725,7 @@ class ManFormat(OutputFormat): self.output_highlight(sections[section]) =20 def out_typedef(self, fname, name, args): - module =3D args.get('module') + module =3D self.modulename typedef =3D args.get('typedef') purpose =3D args.get('purpose') sectionlist =3D args.get('sectionlist', []) @@ -741,7 +741,7 @@ class ManFormat(OutputFormat): self.output_highlight(sections.get(section)) =20 def out_struct(self, fname, name, args): - module =3D args.get('module') + module =3D self.modulename struct_type =3D args.get('type') struct_name =3D args.get('struct') purpose =3D args.get('purpose') diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 51ac2d69a587..0c0fa10b942b 100755 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -801,7 +801,6 @@ class KernelDoc: =20 self.output_declaration(decl_type, declaration_name, struct=3Ddeclaration_name, - module=3Dself.entry.modulename, definition=3Ddeclaration, parameterlist=3Dself.entry.parameterlist, parameterdescs=3Dself.entry.parameterdescs, @@ -879,7 +878,6 @@ class KernelDoc: =20 self.output_declaration('enum', declaration_name, enum=3Ddeclaration_name, - module=3Dself.config.modulename, parameterlist=3Dself.entry.parameterlist, parameterdescs=3Dself.entry.parameterdescs, parameterdesc_start_lines=3Dself.entry.par= ameterdesc_start_lines, @@ -1051,7 +1049,6 @@ class KernelDoc: self.output_declaration(decl_type, declaration_name, function=3Ddeclaration_name, typedef=3DTrue, - module=3Dself.config.modulename, functiontype=3Dreturn_type, parameterlist=3Dself.entry.parameterli= st, parameterdescs=3Dself.entry.parameterd= escs, @@ -1066,7 +1063,6 @@ class KernelDoc: self.output_declaration(decl_type, declaration_name, function=3Ddeclaration_name, typedef=3DFalse, - module=3Dself.config.modulename, functiontype=3Dreturn_type, parameterlist=3Dself.entry.parameterli= st, parameterdescs=3Dself.entry.parameterd= escs, @@ -1113,7 +1109,6 @@ class KernelDoc: self.output_declaration(decl_type, declaration_name, function=3Ddeclaration_name, typedef=3DTrue, - module=3Dself.entry.modulename, functiontype=3Dreturn_type, parameterlist=3Dself.entry.parameterli= st, parameterdescs=3Dself.entry.parameterd= escs, @@ -1141,7 +1136,6 @@ class KernelDoc: =20 self.output_declaration('typedef', declaration_name, typedef=3Ddeclaration_name, - module=3Dself.entry.modulename, sectionlist=3Dself.entry.sectionlist, sections=3Dself.entry.sections, section_start_lines=3Dself.entry.secti= on_start_lines, @@ -1630,8 +1624,7 @@ class KernelDoc: self.output_declaration("doc", self.entry.identifier, sectionlist=3Dself.entry.sectionlist, sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.secti= on_start_lines, - module=3Dself.config.modulename) + section_start_lines=3Dself.entry.secti= on_start_lines) self.reset_state(ln) =20 elif doc_content.search(line): --=20 2.48.1 From nobody Fri Dec 19 20:32:39 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 107DB1DED63; Wed, 19 Feb 2025 13:57:59 +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=1739973480; cv=none; b=Ue4DGvjsYM5owbl+G5WpaDs6LzboL8iLwgS/nHDNy3L9HBbueYPGHoaV5ciENlF3ArmCZzblVWW4jWlAzh/58YoOOMBOXoy+/OpHFBXRsaO4FqTq6YlI96//EQYhlks2Ne1Aj0cpplG1vBNYLZAClBy7RpjX3H6YIG3ipIOL4OM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739973480; c=relaxed/simple; bh=7R366oYKmHOPpm8w8SRMstX38EO00rzyOjDKwrc/HvM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=kCLHFxorVDkVxxrCFgZjzqJGpYYdWEHkxBxoQFucbdHktncPMkjAZZPNdS4ceRVDBmFS/xVjlm6IT8abMYvsrqs6wzyrahKgZtTXALA5Nnkrtm+2Gkeg9e9JHAPFdZUEg8vg01jlYpQ8AxytvG3hOtgTkJH7l8Aee9L1rDNd9xk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=R6P5eAMg; 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="R6P5eAMg" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 92AB3C4CED6; Wed, 19 Feb 2025 13:57:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1739973479; bh=7R366oYKmHOPpm8w8SRMstX38EO00rzyOjDKwrc/HvM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=R6P5eAMgEhntbiTEVUOj/hhs4F3GyrUMl49CX5ax4h1XPzEwNoCTKvymaKMt+NSX2 Gzf9N5LIuHTomtvVCIRppzNkDgPsLGGiyft4HWrNbhsFTnjj+LiNCxxueAJBZuroqJ gWv2Tx3hLGFq5VhzFsVXdAGLKGiM3tUw0wS/mRGi00NjJ+MnJR3I6atPOZBwsuxiNH yei3iN/meR49MHNSF1Vj6DgUZqP7iUFcQJOsdhIxJNPpRS/kuUigetHmnh6likUC3M 9xJ9A44QJybbXG+xQdLfziwNBCxI0fBxXDL7CWW8LDW5ZSZjcbMHu91SzyQcyiwwrx 8zVW0WUeMVCLg== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tkkaL-0000000H1jV-11aI; Wed, 19 Feb 2025 14:57:57 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH 5/6] scripts/kernel-doc.py: properly handle KBUILD_BUILD_TIMESTAMP Date: Wed, 19 Feb 2025 14:57:40 +0100 Message-ID: <35d0f26f8ab2845245b3c3b7817c1e3ab883f069.1739972906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" The logic that handles KBUILD_BUILD_TIMESTAMP is wrong, and adds a dependency of a third party module (dateutil). Fix it. Signed-off-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_files.py | 9 --------- scripts/lib/kdoc/kdoc_output.py | 28 +++++++++++++++++++++------- 2 files changed, 21 insertions(+), 16 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py index a2417cafb1c8..19fe9c6f5352 100755 --- a/scripts/lib/kdoc/kdoc_files.py +++ b/scripts/lib/kdoc/kdoc_files.py @@ -12,9 +12,6 @@ import logging import os import re import sys -from datetime import datetime - -from dateutil import tz =20 from kdoc_parser import KernelDoc from kdoc_output import OutputFormat @@ -136,12 +133,6 @@ class KernelFiles(): if out_style is None: out_style =3D OutputFormat() =20 - dt =3D datetime.now() - if os.environ.get("KBUILD_BUILD_TIMESTAMP", None): - # use UTC TZ - to_zone =3D tz.gettz('UTC') - dt =3D dt.astimezone(to_zone) - if not werror: kcflags =3D os.environ.get("KCFLAGS", None) if kcflags: diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index 13a74a687f89..166fcabbb4cf 100755 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -18,8 +18,6 @@ import os import re from datetime import datetime =20 -from dateutil import tz - from kdoc_parser import KernelDoc, type_param from kdoc_re import Re =20 @@ -584,6 +582,15 @@ class ManFormat(OutputFormat): ) blankline =3D "" =20 + date_formats =3D [ + "%a %b %d %H:%M:%S %Z %Y", + "%a %b %d %H:%M:%S %Y", + "%Y-%m-%d", + "%b %d %Y", + "%B %d %Y", + "%m %d %Y", + ] + def __init__(self, modulename): """ Creates class variables. @@ -595,11 +602,18 @@ class ManFormat(OutputFormat): super().__init__() self.modulename =3D modulename =20 - dt =3D datetime.now() - if os.environ.get("KBUILD_BUILD_TIMESTAMP", None): - # use UTC TZ - to_zone =3D tz.gettz('UTC') - dt =3D dt.astimezone(to_zone) + dt =3D None + tstamp =3D os.environ.get("KBUILD_BUILD_TIMESTAMP") + if tstamp: + for fmt in self.date_formats: + try: + dt =3D datetime.strptime(tstamp, fmt) + break + except ValueError: + pass + + if not dt: + dt =3D datetime.now() =20 self.man_date =3D dt.strftime("%B %Y") =20 --=20 2.48.1 From nobody Fri Dec 19 20:32:39 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 2E34F1EA7FC; Wed, 19 Feb 2025 13:57:59 +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=1739973480; cv=none; b=pGseD1XKjRoYNnGBzZtszIe21YT1PWi6m9GVV1SStu+XPkmNnfumvoCKlhoyqyk3ooAPlIe53NJrHUM/dowVxfbAu87i9r5MItwkPswjU1MLE4fouexeVz2juPc8ZrZlKZbAgpSbXlAnVJ29GIEN6G9iVrqsFQ1acKk3NlPm6Ac= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739973480; c=relaxed/simple; bh=rBaRLeMqhVMdPKl/arUfcC4DaRWWHoHCgWfY19slLGU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=emobX3N31yM2Xy0V9GWCsV0q9B8ho2yGCgAJQD/wnVY/P05vcxbuq46FoQlN4ljvbA2DTtLGnW5YnF/hzYdeDmLTGdRWNjMl26HzrZsxNL1MLdwNOQO+mMHtTj5suendKsbMtNv6J/KtQK3crBbo+b8GHVMrBHQH48YIETWxBkk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ngStJ/MV; 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="ngStJ/MV" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9DB49C4CEEA; Wed, 19 Feb 2025 13:57:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1739973479; bh=rBaRLeMqhVMdPKl/arUfcC4DaRWWHoHCgWfY19slLGU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ngStJ/MVsUwnkG7aIg+T+X+o3GoSHfSNzrOip1z+EmcxYkJiXNFNtFfghK/1qT3if sQ1FjimRwzDNAHGLKVAtsOkvqH0WnU9LReVEL7gTm7pgKZt7qH2lEkmyV9xwrzRjCK 7661RYghivpATmEdbfaQ5ZPIJ6fcmaxkpWwzp2kSQ9ec8S2rGPI20JFcfR1yL/oXMo H+XrgpUSD6z8eX1vD5+nP3QtH9rLTh3d3iX39oITvKDe2nr9hrZEsc9FcU5+AHYlDE h8o2ilVl4Tsp73oILLz3u4rbonDzd9yJsLCcmpPql/4BRWsJxMvBQ8PdXdIp91sfEK kulRxchBWdn3w== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tkkaL-0000000H1jZ-18Zk; Wed, 19 Feb 2025 14:57:57 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH 6/6] scripts/lib/kdoc/kdoc_parser.py: remove a python 3.9 dependency Date: Wed, 19 Feb 2025 14:57:41 +0100 Message-ID: <209f61b25b68dd329e7cf40d9d0bc3b574cc1d3f.1739972906.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" str.removesuffix() was added on Python 3.9, but rstrip() actually does the same thing, as we just want to remove a single character. It is also shorter. So, use it. Signed-off-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 0c0fa10b942b..feac699a3893 100755 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1652,7 +1652,7 @@ class KernelDoc: # Group continuation lines on prototypes if self.state =3D=3D self.STATE_PROTO: if line.endswith("\\"): - prev +=3D line.removesuffix("\\") + prev +=3D line.rstrip("\\") cont =3D True =20 if not prev_ln: --=20 2.48.1