From nobody Sat Oct 4 00:28:09 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 BA1503126AF; Fri, 22 Aug 2025 14:19:48 +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=1755872388; cv=none; b=b0GsjUDmTNNnDk81RcTNoyllu2mWWhHZ2TnBnpxAdEHYJVBG7BbMUY0QmIPdueTxBlBKliKc2DTYZ5dXwP1oDf2RK47vy3wisnYQqn4ytuclhGpHUiAtwaLGVeVLMKUprtTHzaFvR8XQBqQn4a3BVQWsKZmkYkPjQKDYu6S0F4o= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755872388; c=relaxed/simple; bh=Ryz5fK1HBEzZjQk/ZMX2f1BMYW5Jfa7MSrJhKnqCZ5k=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=lqn/XCLvQYelnQ9HGpMNx8tkrml7qsZkHTy8ZvHFQLi0ZsCr2eXqj5csqtLFqwZ+hon29ymcJ6wxL9/ItXEwVSb2UivGbQjxdrSWmQpTCo9/MKpvnI6XM7BN0iQEJIfLJh2MQQ4MCZV4FzTzRfF4U9LKHAb0UdymjQaZB3nSsXA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=nMMdXJGY; 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="nMMdXJGY" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4C6ADC2BCC7; Fri, 22 Aug 2025 14:19:48 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1755872388; bh=Ryz5fK1HBEzZjQk/ZMX2f1BMYW5Jfa7MSrJhKnqCZ5k=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nMMdXJGYKSGznKAOoExjtZnUlnzsuvWOZ58YcVgDJwmaO5DgLCT3+BP9Mm8mmLMgl Ma1pcMrsYrT7/GwlK0f5J739qN/lNkyJR85DFVf0ZyapseGD/y/s0/TO+35f3YJgxi 4HiU4pXLEhwEY04fJHI8aiAV/LEzTHgM3CWWfAIoRjbSrUMqiO6IspVWDdlCikNLU4 XG77DfGxiWITgG9HyQ1xCuN9/EIq9Q/DY8MsRjudJ9UcqEOMpWnzbkQLtxYSEqN1PX P+ByQ1/AyT6DkntItl/lFSAK2PSgfK334goUwnz8GVeF+UpelsWPOfMgCRYNDvYHMp wppBktPGXCD6Q== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1upScM-0000000CCs3-2R59; Fri, 22 Aug 2025 16:19:46 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , Kees Cook , linux-kernel@vger.kernel.org Subject: [PATCH v2 18/24] docs: kernel_include.py: append line numbers to better report errors Date: Fri, 22 Aug 2025 16:19:30 +0200 Message-ID: X-Mailer: git-send-email 2.50.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" It is best to point to the original line of code that generated an error than to point to the beginning of a directive. Add support for it. It should be noticed that this won't work for literal or code blocks, as Sphinx will ignore it, pointing to the beginning of the directive. Yet, when the output is known to be in ReST format, like on TOC, this makes the error a lot more easier to be handled. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/kernel_include.py | 81 ++++++++++++++------------ 1 file changed, 44 insertions(+), 37 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/= kernel_include.py index 79682408105e..90ed8428f776 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -60,6 +60,7 @@ import re import sys =20 from docutils import io, nodes, statemachine +from docutils.statemachine import ViewList from docutils.utils.error_reporting import SafeString, ErrorString from docutils.parsers.rst import directives from docutils.parsers.rst.directives.body import CodeBlock, NumberLines @@ -112,7 +113,14 @@ class KernelInclude(Include): except UnicodeError as error: raise self.severe('Problem with directive:\n%s' % ErrorStr= ing(error)) =20 - def read_rawtext_with_xrefs(self, env, path, output_type): + def xref_text(self, env, path, tab_width): + """ + Read and add contents from a C file parsed to have cross reference= s. + + There are two types of supported output here: + - A C source code with cross-references; + - a TOC table containing cross references. + """ parser =3D ParseDataStructs() parser.parse_file(path) =20 @@ -127,10 +135,33 @@ class KernelInclude(Include): if 'warn-broken' in self.options: env._xref_files.add(path) =20 - if output_type =3D=3D "toc": - return parser.gen_toc() + if "toc" in self.options: + rawtext =3D parser.gen_toc() + else: + rawtext =3D ".. parsed-literal::\n\n" + parser.gen_output() + self.apply_range(rawtext) =20 - return ".. parsed-literal::\n\n" + parser.gen_output() + title =3D os.path.basename(path) + + include_lines =3D statemachine.string2lines(rawtext, tab_width, + convert_whitespace=3DTru= e) + + # Append line numbers data + + startline =3D self.options.get('start-line', None) + + result =3D ViewList() + if startline and startline > 0: + offset =3D startline - 1 + else: + offset =3D 0 + + for ln, line in enumerate(include_lines, start=3Doffset): + result.append(line, path, ln) + + self.state_machine.insert_input(result, path) + + return [] =20 def apply_range(self, rawtext): # Get to-be-included content @@ -195,9 +226,12 @@ class KernelInclude(Include): literal_block +=3D nodes.Text(text, text) return [literal_block] =20 - def code(self, path, include_lines): + def code(self, path, tab_width): """Output a code block""" =20 + include_lines =3D statemachine.string2lines(rawtext, tab_width, + convert_whitespace=3DTru= e) + self.options["source"] =3D path codeblock =3D CodeBlock(self.name, [self.options.pop("code")], # arguments @@ -244,47 +278,20 @@ class KernelInclude(Include): =20 encoding =3D self.options.get("encoding", self.state.document.settings.input_enc= oding) - e_handler =3D self.state.document.settings.input_encoding_error_ha= ndler tab_width =3D self.options.get("tab-width", self.state.document.settings.tab_widt= h) =20 - if "literal" in self.options: - output_type =3D "literal" - elif "code" in self.options: - output_type =3D "code" - else: - output_type =3D "rst" - # Get optional arguments to related to cross-references generation if "generate-cross-refs" in self.options: - if "toc" in self.options: - output_type =3D "toc" - - rawtext =3D self.read_rawtext_with_xrefs(env, path, output_typ= e) - - # When :generate-cross-refs: is used, the input is always a C - # file, so it has to be handled as a parsed-literal - if output_type =3D=3D "rst": - output_type =3D "literal" - - title =3D os.path.basename(path) - else: - rawtext =3D self.read_rawtext(path, encoding) + return self.xref_text(env, path, tab_width) =20 + rawtext =3D self.read_rawtext(path, encoding) rawtext =3D self.apply_range(rawtext) =20 - if output_type =3D=3D "literal": - return self.literal(path, tab_width, rawtext) + if "code" in self.options: + return self.code(path, tab_width, rawtext) =20 - include_lines =3D statemachine.string2lines(rawtext, tab_width, - convert_whitespace=3DTru= e) - - if output_type =3D=3D "code": - return self.code(path, include_lines) - - self.state_machine.insert_input(include_lines, path) - - return [] + return self.literal(path, tab_width, rawtext) =20 # =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =20 --=20 2.50.1