From nobody Sat Feb 7 22:22:02 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 3A4311514E4; Wed, 21 May 2025 09:02:22 +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=1747818143; cv=none; b=tKLR9mJgxKfPZAqJdacJ3QjPszBCnheznzw+ium46aivoL2e8MB+YWUUsivU+5rtx85cs+4cufvdSuLMTDcIte+wx9Vd/Tv4uPBV5XDx5b2+7wXnfC556GBLsXR0V/NUNRsevq/xhOiVmIJOJ7F4fxAdDbqGW5ubd5IjLWxRXO4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1747818143; c=relaxed/simple; bh=6CevvtaHDPmGnEcdPU4+gHZ1doSko2nSV+sN6EtrHpQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=T4PPZdv4kaJKnJPSUAADLhSyXU4mbEfLI5JmI8FsIkvTRqodHN92Hd/HE/34Y/brfwX9YM59jW6AG4ULKc1NDJYW/S1grpr/lRamIZK/3vF0CGOLzpjinLRZ3zMswxcQUHH4BRGadqVfPzZPO8InO8wf9vVbugb289/Bz6S7Ab8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=dyQ94wLP; 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="dyQ94wLP" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B38E7C4CEE4; Wed, 21 May 2025 09:02:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1747818142; bh=6CevvtaHDPmGnEcdPU4+gHZ1doSko2nSV+sN6EtrHpQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=dyQ94wLP607BU8O7Jm1w2hX1m+3gVqtyPucDjS0RV0Vt9ZLOC0/bmVFIDv+tVyXvL Bn1fXGXR6rmVF/UDccdX7c8uTzy4I7IQrE0NAjnd2tzOTJIdVr8T2XJMCFncKDrruw RVJ5uT7SVhxgfGhHVJOfZ8UfLAaDowoOFv5OKia797MroGUICEev7r79JtxY0PFtAi lTqHTSRHqHNaJUcIHEBGYiM2xk59W/jlK2HDKi9gmhqeTJ9aI2smPYl7iPUCeDhAJp JQd9K6qsXqlBL969TQUbUxEWZ427GbokjQAirq9I0zWBA1ShaP/A/qatldblREwtFr r0XqdEg9iYq6w== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uHfLA-00000006L9a-3X2q; Wed, 21 May 2025 11:02:20 +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 v3 1/3] MAINTAINERS: update linux-doc entry to cover new Python scripts Date: Wed, 21 May 2025 11:02:13 +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 Acked-by: Andy Shevchenko --- MAINTAINERS | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/MAINTAINERS b/MAINTAINERS index 20e07e61a148..63218280e802 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 22:22:02 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 579AA238C0A; Wed, 21 May 2025 09:02:23 +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=1747818143; cv=none; b=VdPDJmMma2hKMJfAzpXjpNq+oZamsgZM5ATNreCnfuPdri3K1Z0xoaWH8dEE8jqaDjzQngJNObj8MEssndGRFoiJh8P/44fa2SBYPqb11/FgIHa4yUEKcWy9i2gmYcB9zab4J9LbppJ9N/utmVhpVXgycwFQb3xbuKO7J+F2EQY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1747818143; c=relaxed/simple; bh=xdsIM/oX21o5e6WrNYvFNDZLSWw4Vwh1GOQuXz3gT5s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=McKiW2bihsMFB04T7qtFX15mEKnKHwpze0qtwBykh8GZLJ08URNmHvf1ZU2Q1eY+pw+gflOPdB/3jmBv99BUoRrYDSqBPnaR9GfUZEJJfLmHXFbfaQXcD2kPzP5u4jxjgWdSXdyC/DDvbIJ1hHKbyrxNMTDXvnrl01CiDfObC+M= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=TPDlodbS; 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="TPDlodbS" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B744BC4CEED; Wed, 21 May 2025 09:02:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1747818142; bh=xdsIM/oX21o5e6WrNYvFNDZLSWw4Vwh1GOQuXz3gT5s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=TPDlodbSxJmIaLx4y6M0Tdi4qR/UUjtsliRkx19kqOyVyhiMwt1Ilj0uwbXWz4Mg0 45+J5tyr6V761xJJxJFjuxahYZmqKwvkzOXw95M0tsrpxVvou3ytrf1WOLQ7ysy3T3 gl6XYuGSrcqZzLPkuBe4qkkKc9cRu61NG8B9UnQ/i12x0k5rCP+sFs3yhbjqXH/IkQ NSAZD4SjADX9nIJtfbS/yIWmqHBCxyDtgQ0cBaC97GA93ZyLe8X42H3rJu2xOEhAaM eU1bgzYREmZiAPh6orGGvci3wmK5jfUsHnGdWZU6jrNEkMoDSb83rMQooQVRmKTOko UTRrJ1Zr3lBDQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uHfLA-00000006L9e-3dnY; Wed, 21 May 2025 11:02:20 +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 v3 2/3] docs: kerneldoc.py: simplify exception handling logic Date: Wed, 21 May 2025 11:02:14 +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 Acked-by: Andy Shevchenko --- 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 22:22:02 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 3A4932356DE; Wed, 21 May 2025 09:02:22 +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=1747818143; cv=none; b=NZnBb35ItxWDmWqbfst3KjfurGIubET1K0AU1eHOotl6x6cjmUeIRUuqehKkmivfxCbAUN9C0+LvOufNu4EjHLxEspSW/ZxOBZXRch1pgbiDDi8KgarKY4CX9RTIJCuakvF1SO56RRZMoIGCT9gvHJoWByFeTqfVxwvORMr9bmw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1747818143; c=relaxed/simple; bh=1F+XLvKJN8mGHglQB9+YpWwhAiCnby4yAK6uXiE4F54=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=USDrPRxAcIo70bty9fs5le7/b2x4iRrKFXHzjGQoGP62UxzepY8QqGtrxozzD5TXwCGKmqap7Gj84+8XwC03t80/Jkn4+Q8g5zbg95JFhq27qpgePHZa4WpLozE7zmxJDpGB46WgcLKXp0ERtStF8WrdyLOXkbWmFV4qqZgsuEs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ayiixZE5; 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="ayiixZE5" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B9554C4CEEF; Wed, 21 May 2025 09:02:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1747818142; bh=1F+XLvKJN8mGHglQB9+YpWwhAiCnby4yAK6uXiE4F54=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ayiixZE5PjtMegiMEfcN/b+gD+9JXxiPApEbPBI10p8y5YNhm8E+cbeHh0Q1Q/Xx9 GHDoq43xiuCMOPRTcH19fuDas5cqwPPqzezfr30bVtkHaAFLZLIBkFmf6rdt57ka4m P4DLaUNIMg2qVGoTXhcfbK1FvaXvvwX/Er+NZFC1EhpJaUnFBwcBSTwRW7vvpQJ8v7 QUkYNURhI6DEssc9zzwS4Ou2YqT2Yvo9w8Dmh0GzOAnGyxX4CB0wP48VjS0CGmlgqx /08ALbHYE77Vp6qknNH371+e044qMZ+bMsipmpy5aYcxrfI6K340DTLl5Dt7WtOhZR NHWR0OpN6U9Ug== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uHfLA-00000006L9i-3ki0; Wed, 21 May 2025 11:02:20 +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 v3 3/3] scripts: kernel-doc: prevent a KeyError when checking output Date: Wed, 21 May 2025 11:02:15 +0200 Message-ID: <4efa177f2157a7ec009cc197dfc2d87e6f32b165.1747817887.git.mchehab+huawei@kernel.org> 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 Acked-by: Andy Shevchenko --- 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