From nobody Sat Feb 7 20:53:01 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 23FF4233739; Wed, 21 May 2025 06:59:45 +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=1747810786; cv=none; b=iTBfKi53b7C/zSRuNv5XPMT2doWmcf4SGDE0le7rXUaUZmxXp1bBVrNbFAfpyn55bTjwJOrLU2nJ+GcTtJ5mJTon2XD4uDx9OvkQvOLr0TKO4X2AorX6yWARzgdleJ6BNTk3lWygVl+ft73dwa2s08rlvF+wUBiKsTgdPdU56tI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1747810786; c=relaxed/simple; bh=fEgVgn8ddmuG94XtJzRW64JNMVcuU+HToQCr20S4KM0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=QKT/b7tfTFms6jXnuQhIRMPyrZbXmwUKDVGYrmztK4t37czRkcvFKryW0J9k5rc5Frq89FiPT3BODxZYKWlDE74IYH8QOoeBpCfFo/2L4BQ4aGlcdvckq+NAQna4/QIQ15Pf2EztsiTPhBJDE7MImUjgeun+w51znFNRoqcf/90= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=t7ejPxcZ; 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="t7ejPxcZ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9C462C4AF0C; Wed, 21 May 2025 06:59:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1747810785; bh=fEgVgn8ddmuG94XtJzRW64JNMVcuU+HToQCr20S4KM0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=t7ejPxcZbOpZpdKCOyr9BqqdotlnlpD11PjGDqRYksgYEOKQNFp6VFaEf09JysweT 3JZdMk5d7MmMXRygA36/tinpeuEBrIz953zTixh2npTEr0+FiOdt1Zb74jq6SUIUHy UGmhAYw44+0qCMnMHxqCpzGaPaJvrmFsE9whgj4qyKZ7AkQvhfTpW2fV2ykEw3YJZb TR6QKJubMiwkK4R7V2y27xrGPPat3woG5YORMBm1BvB+Cr1GOmbKUbeG5TR1CDeQOk dGBrC3xKx55YB1JgkAAbtBWQ+5fjXJzbT98akdW6TtQNqOVsTptVEq+xYb9GvmWruJ /AGRqxei7vg3Q== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uHdQV-00000006IFy-2ywJ; Wed, 21 May 2025 08:59:43 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Andy Shevchenko" , "Masahiro Yamada" , "Nathan Chancellor" , "Nicolas Schier" , "Randy Dunlap" , "Stephen Rothwell" , linux-doc@vger.kernel.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 1/3] MAINTAINERS: update linux-doc entry to cover new Python scripts Date: Wed, 21 May 2025 08:59:31 +0200 Message-ID: X-Mailer: git-send-email 2.49.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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Changes to ABI and kernel-doc need to be c/c linux-doc. Update the maintainer's entry to cover those files. Signed-off-by: Mauro Carvalho Chehab Acked-by: Akira Yokosawa --- MAINTAINERS | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/MAINTAINERS b/MAINTAINERS index 20e07e61a148..a668808769b6 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7173,7 +7173,10 @@ T: git git://git.lwn.net/linux.git docs-next F: Documentation/ F: scripts/check-variable-fonts.sh F: scripts/documentation-file-ref-check -F: scripts/kernel-doc +F: scripts/get_abi.py +F: scripts/kernel-doc* +F scripts/lib/abi/* +F scripts/lib/kdoc/* F: scripts/sphinx-pre-install X: Documentation/ABI/ X: Documentation/admin-guide/media/ --=20 2.49.0 From nobody Sat Feb 7 20:53:01 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 23F9623372E; Wed, 21 May 2025 06:59:45 +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=1747810786; cv=none; b=AQpzb6M41d2m/FlDb+NMnXXeIDDCoBHpGqDpbYZWusxaclVE6KScLCj+q6bRN59q5Vx/Okxs4iA8WdFVrnf1nXN1hUnHYh1/wxBVrYbr75bk3lVpMQvrYbUfTH4fq3yKoPArN1uiRzihdHWgiAn8n+39O4sOIxLzxpNwgsCUuUY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1747810786; c=relaxed/simple; bh=QmqgEQ8bcs2MU/3P3b2x9mP+Nq70CbfNSXA3jCaK9lo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=YcqI2TszoxOL4tSpQIV3Z1oqxK8TXJzveia0PrZ1lg4FE9J3R3M7/xqai+CphPjLnNb95DpoR5DuHt2NvbNFamKLfS43jpqxguG95FHhB/sqHeLNacDYSdC5fP93eFJhGzCQxU/sWH06homb7bzTF11y/+2kLZInjfQzzIgWVpM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=GRw0jEyi; 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="GRw0jEyi" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9A212C4AF09; Wed, 21 May 2025 06:59:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1747810785; bh=QmqgEQ8bcs2MU/3P3b2x9mP+Nq70CbfNSXA3jCaK9lo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GRw0jEyi/eITQSjF4y089HbrrSDUYJhZ/6lCr78qfPf06LqiWesdMMQzjJ3KGeO0X YrDiBZ3DnkR3DYt/u19mUdvZFL/hZ69arx+UvbR9vTk+Q+bZu9nScCzfpGsrcP2BMv GGYEhhcQW4vDv6k90z43a9FC+7xvT+PlH7y4lryIOIio3eAVTCgWosuLl7LilJ6r9l S5kWvkI63qySLDqGlQa8vQMaRHd7m9SdQTQZqD6kUzBTjV75gthrRRq6/f0ahHEVDx G/6aa3rwuwifQblU2w3otPKnFN/Hf/IJ+VkH5LcMobFFG9bQzPimRjROklj4HhczEm gBQSgE/wpwe5A== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uHdQV-00000006IG2-36Di; Wed, 21 May 2025 08:59:43 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Andy Shevchenko" , "Masahiro Yamada" , "Nathan Chancellor" , "Nicolas Schier" , "Randy Dunlap" , "Stephen Rothwell" , Kees Cook , linux-doc@vger.kernel.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 2/3] docs: kerneldoc.py: simplify exception handling logic Date: Wed, 21 May 2025 08:59:32 +0200 Message-ID: X-Mailer: git-send-email 2.49.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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Get rid of logger.verbose() which is causing the logger to not work. Also, instead of having try/except everywhere, place them on a common place. While here, get rid of some bogus logs. Signed-off-by: Mauro Carvalho Chehab Acked-by: Akira Yokosawa --- Documentation/sphinx/kerneldoc.py | 108 +++++++++++++----------------- 1 file changed, 45 insertions(+), 63 deletions(-) diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerne= ldoc.py index b713a2c4a615..b818d4c77924 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -40,6 +40,7 @@ from docutils.parsers.rst import directives, Directive import sphinx from sphinx.util.docutils import switch_source_input from sphinx.util import logging +from pprint import pformat =20 srctree =3D os.path.abspath(os.environ["srctree"]) sys.path.insert(0, os.path.join(srctree, "scripts/lib/kdoc")) @@ -49,7 +50,7 @@ from kdoc_output import RestFormat =20 __version__ =3D '1.0' kfiles =3D None -logger =3D logging.getLogger('kerneldoc') +logger =3D logging.getLogger(__name__) =20 def cmd_str(cmd): """ @@ -190,46 +191,31 @@ class KernelDocDirective(Directive): =20 return cmd =20 - def run_cmd(self): + def run_cmd(self, cmd): """ Execute an external kernel-doc command. """ =20 env =3D self.state.document.settings.env - cmd =3D self.handle_args() - - if self.verbose >=3D 1: - print(cmd_str(cmd)) - node =3D nodes.section() =20 - try: - logger.verbose("calling kernel-doc '%s'" % (" ".join(cmd))) + p =3D subprocess.Popen(cmd, stdout=3Dsubprocess.PIPE, stderr=3Dsub= process.PIPE) + out, err =3D p.communicate() =20 - p =3D subprocess.Popen(cmd, stdout=3Dsubprocess.PIPE, stderr= =3Dsubprocess.PIPE) - out, err =3D p.communicate() + out, err =3D codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-= 8') =20 - out, err =3D codecs.decode(out, 'utf-8'), codecs.decode(err, '= utf-8') + if p.returncode !=3D 0: + sys.stderr.write(err) =20 - if p.returncode !=3D 0: - sys.stderr.write(err) - - logger.warning("kernel-doc '%s' failed with return code %d" - % (" ".join(cmd), p.returncode)) - return [nodes.error(None, nodes.paragraph(text =3D "kernel= -doc missing"))] - elif env.config.kerneldoc_verbosity > 0: - sys.stderr.write(err) - - except Exception as e: # pylint: disable=3DW0703 - logger.warning("kernel-doc '%s' processing failed with: %s" % - (" ".join(cmd), str(e))) + logger.warning("kernel-doc '%s' failed with return code %d" + % (" ".join(cmd), p.returncode)) return [nodes.error(None, nodes.paragraph(text =3D "kernel-doc= missing"))] + elif env.config.kerneldoc_verbosity > 0: + sys.stderr.write(err) =20 filenames =3D self.parse_args["file_list"] for filename in filenames: - ret =3D self.parse_msg(filename, node, out, cmd) - if ret: - return ret + self.parse_msg(filename, node, out, cmd) =20 return node.children =20 @@ -240,40 +226,31 @@ class KernelDocDirective(Directive): =20 env =3D self.state.document.settings.env =20 - try: - lines =3D statemachine.string2lines(out, self.tab_width, - convert_whitespace=3DTrue) - result =3D ViewList() + lines =3D statemachine.string2lines(out, self.tab_width, + convert_whitespace=3DTrue) + result =3D ViewList() =20 - lineoffset =3D 0; - line_regex =3D re.compile(r"^\.\. LINENO ([0-9]+)$") - for line in lines: - match =3D line_regex.search(line) - if match: - # sphinx counts lines from 0 - lineoffset =3D int(match.group(1)) - 1 - # we must eat our comments since the upset the markup - else: - doc =3D str(env.srcdir) + "/" + env.docname + ":" + st= r(self.lineno) - result.append(line, doc + ": " + filename, lineoffset) - lineoffset +=3D 1 + lineoffset =3D 0; + line_regex =3D re.compile(r"^\.\. LINENO ([0-9]+)$") + for line in lines: + match =3D line_regex.search(line) + if match: + # sphinx counts lines from 0 + lineoffset =3D int(match.group(1)) - 1 + # we must eat our comments since the upset the markup + else: + doc =3D str(env.srcdir) + "/" + env.docname + ":" + str(se= lf.lineno) + result.append(line, doc + ": " + filename, lineoffset) + lineoffset +=3D 1 =20 - self.do_parse(result, node) + self.do_parse(result, node) =20 - except Exception as e: # pylint: disable=3DW0703 - logger.warning("kernel-doc '%s' processing failed with: %s" % - (cmd_str(cmd), str(e))) - return [nodes.error(None, nodes.paragraph(text =3D "kernel-doc= missing"))] - - return None - - def run_kdoc(self, kfiles): + def run_kdoc(self, cmd, kfiles): """ Execute kernel-doc classes directly instead of running as a separa= te command. """ =20 - cmd =3D self.handle_args() env =3D self.state.document.settings.env =20 node =3D nodes.section() @@ -282,22 +259,27 @@ class KernelDocDirective(Directive): filenames =3D self.parse_args["file_list"] =20 for filename, out in kfiles.msg(**self.msg_args, filenames=3Dfilen= ames): - if self.verbose >=3D 1: - print(cmd_str(cmd)) - - ret =3D self.parse_msg(filename, node, out, cmd) - if ret: - return ret + self.parse_msg(filename, node, out, cmd) =20 return node.children =20 def run(self): global kfiles =20 - if kfiles: - return self.run_kdoc(kfiles) - else: - return self.run_cmd() + cmd =3D self.handle_args() + if self.verbose >=3D 1: + logger.info(cmd_str(cmd)) + + try: + if kfiles: + return self.run_kdoc(cmd, kfiles) + else: + return self.run_cmd(cmd) + + except Exception as e: # pylint: disable=3DW0703 + logger.warning("kernel-doc '%s' processing failed with: %s" % + (cmd_str(cmd), pformat(e))) + return [nodes.error(None, nodes.paragraph(text =3D "kernel-doc= missing"))] =20 def do_parse(self, result, node): with switch_source_input(self.state, result): --=20 2.49.0 From nobody Sat Feb 7 20:53:01 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 24054233D64; Wed, 21 May 2025 06:59:45 +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=1747810786; cv=none; b=YGQAQJJ/VHMlXFLQNGcDvNWn35MDTQx41zujQEDHGS0Zh4ikhwKkO3oZzF+yXJCLOg80JT1ohlAKv7ZG0pMSLaM7SSVQ3HW3/ACYGHSbdaNdAjnKbDiEfnFfMiCLRKR8nU1wj7OTEHN1gfJN9ImRoo8G6m18AdtzES1WVqkgTYo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1747810786; c=relaxed/simple; bh=zrs4cXgnOa//B/Txk8KhjILwuaI02i9DB4tFgWygRDc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=YUdGuaAROhaxt2m1WDvkN+9mkiLoHtp1n/SM8X/aO0QR3NEvUzFne7EwBvOlM6/O6RABuwTuuF7B67D+mXWrgp1YrAeaJSUVaQYTlevdNenecVUy51mxnbSjxxRNbOboXLzUvoeKiHaRNNYiHjNuQUuYPJCqycim3qEboNkymrM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=X26GFF/S; 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="X26GFF/S" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9840BC4CEEB; Wed, 21 May 2025 06:59:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1747810785; bh=zrs4cXgnOa//B/Txk8KhjILwuaI02i9DB4tFgWygRDc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=X26GFF/SWaINIpDsWh3rDNXnbBSz2OXs5ORJKKrIKZ2pELxcpHw2W2jzNRwRYsanS 9Zh6XSJAX3seUSVzUxmLP1IeG8CrsPwdmh5Dj6oPuqUr8oSMbUdZYOQXsprAYTKhJB mVQpNSrl94TcgfixJoteslTH9kyfcnAPWvgxUzCYGm96WCNag8sm6jiGIQcPJ4lk8/ Og4R8SL+EHOXR+GsBdFZYPzaiNeRTYAaGuG9yxZALGH3JnB4/KAAOWhnnIUF9M9omc 6VN+qPxgtujCWziRtyPz6WiLBNBmWlasMWiu9qUGYaEGx0o2NIrNdEjcGw64DB59tw 5Rx8BQ54ADwyA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uHdQV-00000006IG6-3DTs; Wed, 21 May 2025 08:59:43 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Andy Shevchenko" , "Masahiro Yamada" , "Nathan Chancellor" , "Nicolas Schier" , "Randy Dunlap" , "Stephen Rothwell" , linux-doc@vger.kernel.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 3/3] scripts: kernel-doc: prevent a KeyError when checking output Date: Wed, 21 May 2025 08:59:33 +0200 Message-ID: X-Mailer: git-send-email 2.49.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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" If a file sent to KernelFiles.msg() method doesn't exist, instead of producing a KeyError, output an error message. Reported-by: Randy Dunlap Closes: https://lore.kernel.org/linux-doc/cover.1747719873.git.mchehab+huaw= ei@kernel.org/T/#ma43ae9d8d0995b535cf5099e5381dace0410de04 Signed-off-by: Mauro Carvalho Chehab Acked-by: Akira Yokosawa --- 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 630aa5ca6460..9be4a64df71d 100644 --- a/scripts/lib/kdoc/kdoc_files.py +++ b/scripts/lib/kdoc/kdoc_files.py @@ -271,6 +271,10 @@ class KernelFiles(): no_doc_sections) =20 msg =3D "" + if fname not in self.results: + self.config.log.warning("No kernel-doc for file %s", fname) + continue + for name, arg in self.results[fname]: m =3D self.out_msg(fname, name, arg) =20 --=20 2.49.0