Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1# SPDX-License-Identifier: GPL-2.0
2# Copyright 2019 Jonathan Corbet <corbet@lwn.net>
3#
4# Apply kernel-specific tweaks after the initial document processing
5# has been done.
6#
7from docutils import nodes
8import sphinx
9from sphinx import addnodes
10from sphinx.errors import NoUri
11import re
12from itertools import chain
13
14from kernel_abi import get_kernel_abi
15
16#
17# Regex nastiness. Of course.
18# Try to identify "function()" that's not already marked up some
19# other way. Sphinx doesn't like a lot of stuff right after a
20# :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last
21# bit tries to restrict matches to things that won't create trouble.
22#
23RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=re.ASCII)
24
25#
26# Sphinx 3 uses a different C role for each one of struct, union, enum and
27# typedef
28#
29RE_struct = re.compile(r'\b(struct)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
30RE_union = re.compile(r'\b(union)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
31RE_enum = re.compile(r'\b(enum)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
32RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
33
34#
35# Detects a reference to a documentation page of the form Documentation/... with
36# an optional extension
37#
38RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.(rst|txt)')
39RE_abi_file = re.compile(r'(\bDocumentation/ABI/[\w\-/]+)')
40RE_abi_symbol = re.compile(r'(\b/(sys|config|proc)/[\w\-/]+)')
41
42RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
43
44#
45# Reserved C words that we should skip when cross-referencing
46#
47Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ]
48
49#
50# Common English words that should not be recognized as C identifiers
51# when following struct/union/enum/typedef keywords.
52# Example: "a simple struct that" in workqueue.rst should not be marked as code.
53#
54Skipidentifiers = [ 'that', 'which', 'where', 'whose' ]
55
56#
57# Many places in the docs refer to common system calls. It is
58# pointless to try to cross-reference them and, as has been known
59# to happen, somebody defining a function by these names can lead
60# to the creation of incorrect and confusing cross references. So
61# just don't even try with these names.
62#
63Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap',
64 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl',
65 'socket' ]
66
67c_namespace = ''
68
69#
70# Detect references to commits.
71#
72RE_git = re.compile(r'commit\s+(?P<rev>[0-9a-f]{12,40})(?:\s+\(".*?"\))?',
73 flags=re.IGNORECASE | re.DOTALL)
74
75def markup_refs(docname, app, node):
76 t = node.astext()
77 done = 0
78 repl = [ ]
79 #
80 # Associate each regex with the function that will markup its matches
81 #
82
83 markup_func = {RE_doc: markup_doc_ref,
84 RE_abi_file: markup_abi_file_ref,
85 RE_abi_symbol: markup_abi_ref,
86 RE_function: markup_func_ref_sphinx3,
87 RE_struct: markup_c_ref,
88 RE_union: markup_c_ref,
89 RE_enum: markup_c_ref,
90 RE_typedef: markup_c_ref,
91 RE_git: markup_git}
92
93 match_iterators = [regex.finditer(t) for regex in markup_func]
94 #
95 # Sort all references by the starting position in text
96 #
97 sorted_matches = sorted(chain(*match_iterators), key=lambda m: m.start())
98 for m in sorted_matches:
99 #
100 # Include any text prior to match as a normal text node.
101 #
102 if m.start() > done:
103 repl.append(nodes.Text(t[done:m.start()]))
104
105 #
106 # Call the function associated with the regex that matched this text and
107 # append its return to the text
108 #
109 repl.append(markup_func[m.re](docname, app, m))
110
111 done = m.end()
112 if done < len(t):
113 repl.append(nodes.Text(t[done:]))
114 return repl
115
116#
117# Keep track of cross-reference lookups that failed so we don't have to
118# do them again.
119#
120failed_lookups = { }
121def failure_seen(target):
122 return (target) in failed_lookups
123def note_failure(target):
124 failed_lookups[target] = True
125
126#
127# In sphinx3 we can cross-reference to C macro and function, each one with its
128# own C role, but both match the same regex, so we try both.
129#
130def markup_func_ref_sphinx3(docname, app, match):
131 base_target = match.group(2)
132 target_text = nodes.Text(match.group(0))
133 possible_targets = [base_target]
134 # Check if this document has a namespace, and if so, try
135 # cross-referencing inside it first.
136 if c_namespace:
137 possible_targets.insert(0, c_namespace + "." + base_target)
138
139 if base_target not in Skipnames:
140 for target in possible_targets:
141 if (target not in Skipfuncs) and not failure_seen(target):
142 lit_text = nodes.literal(classes=['xref', 'c', 'c-func'])
143 lit_text += target_text
144 xref = add_and_resolve_xref(app, docname, 'c', 'function',
145 target, contnode=lit_text)
146 if xref:
147 return xref
148 note_failure(target)
149
150 return target_text
151
152def markup_c_ref(docname, app, match):
153 class_str = {RE_struct: 'c-struct',
154 RE_union: 'c-union',
155 RE_enum: 'c-enum',
156 RE_typedef: 'c-type',
157 }
158 reftype_str = {RE_struct: 'struct',
159 RE_union: 'union',
160 RE_enum: 'enum',
161 RE_typedef: 'type',
162 }
163
164 base_target = match.group(2)
165 target_text = nodes.Text(match.group(0))
166 possible_targets = [base_target]
167 # Check if this document has a namespace, and if so, try
168 # cross-referencing inside it first.
169 if c_namespace:
170 possible_targets.insert(0, c_namespace + "." + base_target)
171
172 # Skip common English words that match identifier pattern but are not C code.
173 if base_target in Skipidentifiers:
174 return target_text
175
176 if base_target not in Skipnames:
177 for target in possible_targets:
178 if not (match.re == RE_function and target in Skipfuncs):
179 lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]])
180 lit_text += target_text
181 xref = add_and_resolve_xref(app, docname, 'c',
182 reftype_str[match.re], target,
183 contnode=lit_text)
184 if xref:
185 return xref
186
187 return target_text
188
189#
190# Try to replace a documentation reference of the form Documentation/... with a
191# cross reference to that page
192#
193def markup_doc_ref(docname, app, match):
194 absolute = match.group(1)
195 target = match.group(2)
196 if absolute:
197 target = "/" + target
198
199 xref = add_and_resolve_xref(app, docname, 'std', 'doc', target)
200 if xref:
201 return xref
202 else:
203 return nodes.Text(match.group(0))
204
205#
206# Try to replace a documentation reference for ABI symbols and files
207# with a cross reference to that page
208#
209def markup_abi_ref(docname, app, match, warning=False):
210 kernel_abi = get_kernel_abi()
211
212 fname = match.group(1)
213 target = kernel_abi.xref(fname)
214
215 # Kernel ABI doesn't describe such file or symbol
216 if not target:
217 if warning:
218 kernel_abi.log.warning("%s not found", fname)
219 return nodes.Text(match.group(0))
220
221 xref = add_and_resolve_xref(app, docname, 'std', 'ref', target)
222 if xref:
223 return xref
224 else:
225 return nodes.Text(match.group(0))
226
227def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None):
228 #
229 # Go through the dance of getting an xref out of the corresponding domain
230 #
231 dom_obj = app.env.domains[domain]
232 pxref = addnodes.pending_xref('', refdomain = domain, reftype = reftype,
233 reftarget = target, modname = None,
234 classname = None, refexplicit = False)
235
236 #
237 # XXX The Latex builder will throw NoUri exceptions here,
238 # work around that by ignoring them.
239 #
240 try:
241 xref = dom_obj.resolve_xref(app.env, docname, app.builder, reftype,
242 target, pxref, contnode)
243 except NoUri:
244 xref = None
245
246 if xref:
247 return xref
248 #
249 # We didn't find the xref; if a container node was supplied,
250 # mark it as a broken xref
251 #
252 if contnode:
253 contnode['classes'].append("broken_xref")
254 return contnode
255
256#
257# Variant of markup_abi_ref() that warns when a reference is not found
258#
259def markup_abi_file_ref(docname, app, match):
260 return markup_abi_ref(docname, app, match, warning=True)
261
262
263def get_c_namespace(app, docname):
264 source = app.env.doc2path(docname)
265 with open(source) as f:
266 for l in f:
267 match = RE_namespace.search(l)
268 if match:
269 return match.group(1)
270 return ''
271
272def markup_git(docname, app, match):
273 # While we could probably assume that we are running in a git
274 # repository, we can't know for sure, so let's just mechanically
275 # turn them into git.kernel.org links without checking their
276 # validity. (Maybe we can do something in the future to warn about
277 # these references if this is explicitly requested.)
278 text = match.group(0)
279 rev = match.group('rev')
280 return nodes.reference('', nodes.Text(text),
281 refuri=f'https://git.kernel.org/torvalds/c/{rev}')
282
283def auto_markup(app, doctree, name):
284 global c_namespace
285 c_namespace = get_c_namespace(app, name)
286 def text_but_not_a_reference(node):
287 # The nodes.literal test catches ``literal text``, its purpose is to
288 # avoid adding cross-references to functions that have been explicitly
289 # marked with cc:func:.
290 if not isinstance(node, nodes.Text) or isinstance(node.parent, nodes.literal):
291 return False
292
293 child_of_reference = False
294 parent = node.parent
295 while parent:
296 if isinstance(parent, nodes.Referential):
297 child_of_reference = True
298 break
299 parent = parent.parent
300 return not child_of_reference
301
302 #
303 # This loop could eventually be improved on. Someday maybe we
304 # want a proper tree traversal with a lot of awareness of which
305 # kinds of nodes to prune. But this works well for now.
306 #
307 for para in doctree.traverse(nodes.paragraph):
308 for node in para.traverse(condition=text_but_not_a_reference):
309 node.parent.replace(node, markup_refs(name, app, node))
310
311def setup(app):
312 app.connect('doctree-resolved', auto_markup)
313 return {
314 'parallel_read_safe': True,
315 'parallel_write_safe': True,
316 }