From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: Wed, 1 Oct 2025 14:49:26 +0000 (+0200)
Subject: docs: kernel_include.py: fix line numbers for TOC
X-Git-Tag: v6.19-rc1~184^2~61^2~20
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3ed9521772880099803619b57056c8d3cec16f27;p=thirdparty%2Flinux.git

docs: kernel_include.py: fix line numbers for TOC

On TOC output, we need to embeed line numbers with ViewList.

Change the parse class to produce a line-number parsed result,
and adjust the output accordingly.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <74eed96e32f79eaaef7a99ffe7c3224fed369c27.1759329363.git.mchehab+huawei@kernel.org>
---

diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py
index f94412cd17c96..ed819e9821c2a 100755
--- a/Documentation/sphinx/kernel_include.py
+++ b/Documentation/sphinx/kernel_include.py
@@ -104,6 +104,7 @@ logger = logging.getLogger(__name__)
 
 RE_DOMAIN_REF = re.compile(r'\\ :(ref|c:type|c:func):`([^<`]+)(?:<([^>]+)>)?`\\')
 RE_SIMPLE_REF = re.compile(r'`([^`]+)`')
+RE_LINENO_REF = re.compile(r'^\s*-\s+LINENO_(\d+):\s+(.*)')
 
 def ErrorString(exc):  # Shamelessly stolen from docutils
     return f'{exc.__class__.__name}: {exc}'
@@ -242,23 +243,32 @@ class KernelInclude(Directive):
         # TOC output is a ReST file, not a literal. So, we can add line
         # numbers
 
-        rawtext = parser.gen_toc()
-
-        include_lines = statemachine.string2lines(rawtext, tab_width,
-                                                  convert_whitespace=True)
-
-        # Append line numbers data
-
         startline = self.options.get('start-line', None)
+        endline = self.options.get('end-line', None)
 
-        result = ViewList()
-        if startline and startline > 0:
-            offset = startline - 1
-        else:
-            offset = 0
+        relpath = os.path.relpath(path, srctree)
 
-        for ln, line in enumerate(include_lines, start=offset):
-            result.append(line, path, ln)
+        result = ViewList()
+        for line in parser.gen_toc().split("\n"):
+            match = RE_LINENO_REF.match(line)
+            if not match:
+                result.append(line, path)
+                continue
+
+            ln, ref = match.groups()
+            ln = int(ln)
+
+            # Filter line range if needed
+            if startline and (ln < startline):
+                continue
+
+            if endline and (ln > endline):
+                continue
+
+            # Sphinx numerates starting with zero, but text editors
+            # and other tools start from one
+            realln = ln + 1
+            result.append(f"- {ref}: {relpath}#{realln}", path, ln)
 
         self.state_machine.insert_input(result, path)
 
diff --git a/tools/docs/lib/parse_data_structs.py b/tools/docs/lib/parse_data_structs.py
index d28471a045f1b..9ad6217121030 100755
--- a/tools/docs/lib/parse_data_structs.py
+++ b/tools/docs/lib/parse_data_structs.py
@@ -422,7 +422,7 @@ class ParseDataStructs:
 
             # Sort symbols alphabetically
             for symbol, (ref, ln) in sorted(refs.items()):
-                text.append(f"* {ref}: line #{ln}")
+                text.append(f"- LINENO_{ln}: {ref}")
 
             text.append("")  # Add empty line between categories