raspi/linux
1
0
Fork 1
mirror of https://github.com/raspberrypi/linux.git synced 2025-12-07 10:29:52 +00:00
Code Issues Projects Releases Wiki Activity

docs: kernel_include.py: append line numbers to better report errors

Browse Source 
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@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/a0953af8b71e64aaf2e0ba4593ad39e19587d50a.1755872208.git.mchehab+huawei@kernel.org
This commit is contained in:
Mauro Carvalho Chehab
2025-08-22 16:19:30 +02:00
committed by Jonathan Corbet
parent e4d91787de
commit 4ad9cabc34
1 changed files with 44 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
Documentation/sphinx/kernel_include.py
View File

@@ -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)
# ==============================================================================