Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kernel_include.py: move rawtext logic to separate functions
The run function is too complex. merge run() and _run() into
a single function and move the read logic to separate functions.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/04776a94c85b6c931c198a149f08b299c9f571a3.1755872208.git.mchehab+huawei@kernel.org
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
012e00dd
39f5f2fa
+43
-39
+43
-39
Documentation/sphinx/kernel_include.py
+43
-39
Documentation/sphinx/kernel_include.py
···
92
92
'exception-file': directives.unchanged,
93
93
})
94
94
95
+
def read_rawtext(self, path, encoding):
96
+
"""Read and process file content with error handling"""
97
+
try:
98
+
self.state.document.settings.record_dependencies.add(path)
99
+
include_file = io.FileInput(source_path=path,
100
+
encoding=encoding,
101
+
error_handler=self.state.document.settings.input_encoding_error_handler)
102
+
except UnicodeEncodeError:
103
+
raise self.severe('Problems with directive path:\n'
104
+
'Cannot encode input file path "%s" '
105
+
'(wrong locale?).' % SafeString(path))
106
+
except IOError as error:
107
+
raise self.severe('Problems with directive path:\n%s.' % ErrorString(error))
108
+
109
+
try:
110
+
return include_file.read()
111
+
except UnicodeError as error:
112
+
raise self.severe('Problem with directive:\n%s' % ErrorString(error))
113
+
114
+
def read_rawtext_with_xrefs(self, env, path):
115
+
parser = ParseDataStructs()
116
+
parser.parse_file(path)
117
+
118
+
if 'exception-file' in self.options:
119
+
source_dir = os.path.dirname(os.path.abspath(
120
+
self.state_machine.input_lines.source(
121
+
self.lineno - self.state_machine.input_offset - 1)))
122
+
exceptions_file = os.path.join(source_dir, self.options['exception-file'])
123
+
parser.process_exceptions(exceptions_file)
124
+
125
+
if self.options.get("start-line") or self.options.get("end-line"):
126
+
raise self.severe('generate-cross-refs can\'t be used with "start-line" or "end-line"')
127
+
128
+
# Store references on a symbol dict to be used at check time
129
+
if 'warn-broken' in self.options:
130
+
env._xref_files.add(path)
131
+
132
+
return parser.gen_output()
133
+
95
134
def run(self):
135
+
"""Include a file as part of the content of this reST file."""
96
136
env = self.state.document.settings.env
97
137
path = os.path.realpath(os.path.expandvars(self.arguments[0]))
98
138
···
144
104
self.arguments[0] = path
145
105
146
106
env.note_dependency(os.path.abspath(path))
147
-
148
-
# return super(KernelInclude, self).run() # won't work, see HINTs in _run()
149
-
return self._run(env)
150
-
151
-
def _run(self, env):
152
-
"""Include a file as part of the content of this reST file."""
153
107
154
108
# HINT: I had to copy&paste the whole Include.run method. I'am not happy
155
109
# with this, but due to security reasons, the Include.run method does
···
173
139
174
140
# Get optional arguments to related to cross-references generation
175
141
if 'generate-cross-refs' in self.options:
176
-
parser = ParseDataStructs()
177
-
parser.parse_file(path)
178
-
179
-
exceptions_file = self.options.get('exception-file')
180
-
if exceptions_file:
181
-
exceptions_file = os.path.join(source_dir, exceptions_file)
182
-
parser.process_exceptions(exceptions_file)
142
+
rawtext = self.read_rawtext_with_xrefs(env, path)
183
143
184
144
title = os.path.basename(path)
185
-
rawtext = parser.gen_output()
145
+
186
146
if startline or endline:
187
147
raise self.severe('generate-cross-refs can\'t be used together with "start-line" or "end-line"')
188
148
189
149
if "code" not in self.options:
190
150
rawtext = ".. parsed-literal::\n\n" + rawtext
191
-
192
-
# Store references on a symbol dict to be used at check time
193
-
if 'warn-broken' in self.options:
194
-
env._xref_files.add(path)
195
151
else:
196
-
try:
197
-
self.state.document.settings.record_dependencies.add(path)
198
-
include_file = io.FileInput(source_path=path, encoding=encoding,
199
-
error_handler=e_handler)
200
-
except UnicodeEncodeError:
201
-
raise self.severe('Problems with "%s" directive path:\n'
202
-
'Cannot encode input file path "%s" '
203
-
"(wrong locale?)." % (self.name, SafeString(path)))
204
-
except IOError as error:
205
-
raise self.severe('Problems with "%s" directive path:\n%s.'
206
-
% (self.name, ErrorString(error)))
207
-
208
-
try:
209
-
if startline or (endline is not None):
210
-
lines = include_file.readlines()
211
-
rawtext = "".join(lines[startline:endline])
212
-
else:
213
-
rawtext = include_file.read()
214
-
except UnicodeError as error:
215
-
raise self.severe('Problem with "%s" directive:\n%s' %
216
-
(self.name, ErrorString(error)))
152
+
rawtext = self.read_rawtext(path, encoding)
217
153
218
154
# start-after/end-before: no restrictions on newlines in match-text,
219
155
# and no restrictions on matching inside lines vs. line boundaries