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