Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/a0953af8b71e64aaf2e0ba4593ad39e19587d50a.1755872208.git.mchehab+huawei@kernel.org
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
4ad9cabc
e4d91787
+44
-37
+44
-37
Documentation/sphinx/kernel_include.py
+44
-37
Documentation/sphinx/kernel_include.py
···
60
60
import sys
61
61
62
62
from docutils import io, nodes, statemachine
63
+
from docutils.statemachine import ViewList
63
64
from docutils.utils.error_reporting import SafeString, ErrorString
64
65
from docutils.parsers.rst import directives
65
66
from docutils.parsers.rst.directives.body import CodeBlock, NumberLines
···
113
112
except UnicodeError as error:
114
113
raise self.severe('Problem with directive:\n%s' % ErrorString(error))
115
114
116
-
def read_rawtext_with_xrefs(self, env, path, output_type):
115
+
def xref_text(self, env, path, tab_width):
116
+
"""
117
+
Read and add contents from a C file parsed to have cross references.
118
+
119
+
There are two types of supported output here:
120
+
- A C source code with cross-references;
121
+
- a TOC table containing cross references.
122
+
"""
117
123
parser = ParseDataStructs()
118
124
parser.parse_file(path)
119
125
···
135
127
if 'warn-broken' in self.options:
136
128
env._xref_files.add(path)
137
129
138
-
if output_type == "toc":
139
-
return parser.gen_toc()
130
+
if "toc" in self.options:
131
+
rawtext = parser.gen_toc()
132
+
else:
133
+
rawtext = ".. parsed-literal::\n\n" + parser.gen_output()
134
+
self.apply_range(rawtext)
140
135
141
-
return ".. parsed-literal::\n\n" + parser.gen_output()
136
+
title = os.path.basename(path)
137
+
138
+
include_lines = statemachine.string2lines(rawtext, tab_width,
139
+
convert_whitespace=True)
140
+
141
+
# Append line numbers data
142
+
143
+
startline = self.options.get('start-line', None)
144
+
145
+
result = ViewList()
146
+
if startline and startline > 0:
147
+
offset = startline - 1
148
+
else:
149
+
offset = 0
150
+
151
+
for ln, line in enumerate(include_lines, start=offset):
152
+
result.append(line, path, ln)
153
+
154
+
self.state_machine.insert_input(result, path)
155
+
156
+
return []
142
157
143
158
def apply_range(self, rawtext):
144
159
# Get to-be-included content
···
226
195
literal_block += nodes.Text(text, text)
227
196
return [literal_block]
228
197
229
-
def code(self, path, include_lines):
198
+
def code(self, path, tab_width):
230
199
"""Output a code block"""
200
+
201
+
include_lines = statemachine.string2lines(rawtext, tab_width,
202
+
convert_whitespace=True)
231
203
232
204
self.options["source"] = path
233
205
codeblock = CodeBlock(self.name,
···
278
244
279
245
encoding = self.options.get("encoding",
280
246
self.state.document.settings.input_encoding)
281
-
e_handler = self.state.document.settings.input_encoding_error_handler
282
247
tab_width = self.options.get("tab-width",
283
248
self.state.document.settings.tab_width)
284
249
285
-
if "literal" in self.options:
286
-
output_type = "literal"
287
-
elif "code" in self.options:
288
-
output_type = "code"
289
-
else:
290
-
output_type = "rst"
291
-
292
250
# Get optional arguments to related to cross-references generation
293
251
if "generate-cross-refs" in self.options:
294
-
if "toc" in self.options:
295
-
output_type = "toc"
252
+
return self.xref_text(env, path, tab_width)
296
253
297
-
rawtext = self.read_rawtext_with_xrefs(env, path, output_type)
298
-
299
-
# When :generate-cross-refs: is used, the input is always a C
300
-
# file, so it has to be handled as a parsed-literal
301
-
if output_type == "rst":
302
-
output_type = "literal"
303
-
304
-
title = os.path.basename(path)
305
-
else:
306
-
rawtext = self.read_rawtext(path, encoding)
307
-
254
+
rawtext = self.read_rawtext(path, encoding)
308
255
rawtext = self.apply_range(rawtext)
309
256
310
-
if output_type == "literal":
311
-
return self.literal(path, tab_width, rawtext)
257
+
if "code" in self.options:
258
+
return self.code(path, tab_width, rawtext)
312
259
313
-
include_lines = statemachine.string2lines(rawtext, tab_width,
314
-
convert_whitespace=True)
315
-
316
-
if output_type == "code":
317
-
return self.code(path, include_lines)
318
-
319
-
self.state_machine.insert_input(include_lines, path)
320
-
321
-
return []
260
+
return self.literal(path, tab_width, rawtext)
322
261
323
262
# ==============================================================================
324
263