Message-ID: <a0953af8b71e64aaf2e0ba4593ad39e19587d50a.1755872208.git.mchehab+huawei@kernel.org>
Date: Fri, 22 Aug 2025 16:19:30 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>,
	Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
	"Mauro Carvalho Chehab" <mchehab+huawei@...nel.org>,
	Kees Cook <mchehab+huawei@...nel.org>,
	linux-kernel@...r.kernel.org
Subject: [PATCH v2 18/24] docs: kernel_include.py: append line numbers to better report errors

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 <mchehab+huawei@...nel.org>
---
 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
 
 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' % ErrorString(error))
 
-    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 references.
+
+        There are two types of supported output here:
+        - A C source code with cross-references;
+        - a TOC table containing cross references.
+        """
         parser = ParseDataStructs()
         parser.parse_file(path)
 
@@ -127,10 +135,33 @@ class KernelInclude(Include):
         if 'warn-broken' in self.options:
             env._xref_files.add(path)
 
-        if output_type == "toc":
-            return parser.gen_toc()
+        if "toc" in self.options:
+            rawtext = parser.gen_toc()
+        else:
+            rawtext = ".. parsed-literal::\n\n" + parser.gen_output()
+            self.apply_range(rawtext)
 
-        return ".. parsed-literal::\n\n" + parser.gen_output()
+        title = os.path.basename(path)
+
+        include_lines = statemachine.string2lines(rawtext, tab_width,
+                                                  convert_whitespace=True)
+
+        # Append line numbers data
+
+        startline = self.options.get('start-line', None)
+
+        result = ViewList()
+        if startline and startline > 0:
+            offset = startline - 1
+        else:
+            offset = 0
+
+        for ln, line in enumerate(include_lines, start=offset):
+            result.append(line, path, ln)
+
+        self.state_machine.insert_input(result, path)
+
+        return []
 
     def apply_range(self, rawtext):
         # Get to-be-included content
@@ -195,9 +226,12 @@ class KernelInclude(Include):
             literal_block += nodes.Text(text, text)
         return [literal_block]
 
-    def code(self, path, include_lines):
+    def code(self, path, tab_width):
         """Output a code block"""
 
+        include_lines = statemachine.string2lines(rawtext, tab_width,
+                                                  convert_whitespace=True)
+
         self.options["source"] = path
         codeblock = CodeBlock(self.name,
                                 [self.options.pop("code")],  # arguments
@@ -244,47 +278,20 @@ class KernelInclude(Include):
 
         encoding = self.options.get("encoding",
                                     self.state.document.settings.input_encoding)
-        e_handler = self.state.document.settings.input_encoding_error_handler
         tab_width = self.options.get("tab-width",
                                      self.state.document.settings.tab_width)
 
-        if "literal" in self.options:
-            output_type = "literal"
-        elif "code" in self.options:
-            output_type = "code"
-        else:
-            output_type = "rst"
-
         # Get optional arguments to related to cross-references generation
         if "generate-cross-refs" in self.options:
-            if "toc" in self.options:
-                 output_type = "toc"
-
-            rawtext = self.read_rawtext_with_xrefs(env, path, output_type)
-
-            # 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 == "rst":
-                output_type = "literal"
-
-            title = os.path.basename(path)
-        else:
-            rawtext = self.read_rawtext(path, encoding)
+            return self.xref_text(env, path, tab_width)
 
+        rawtext = self.read_rawtext(path, encoding)
         rawtext = self.apply_range(rawtext)
 
-        if output_type == "literal":
-            return self.literal(path, tab_width, rawtext)
+        if "code" in self.options:
+            return self.code(path, tab_width, rawtext)
 
-        include_lines = statemachine.string2lines(rawtext, tab_width,
-                                                  convert_whitespace=True)
-
-        if output_type == "code":
-            return self.code(path, include_lines)
-
-        self.state_machine.insert_input(include_lines, path)
-
-        return []
+        return self.literal(path, tab_width, rawtext)
 
 # ==============================================================================
 
-- 
2.50.1

Powered by blists - more mailing lists