Commit | Line | Data |
---|---|---|
d74b0d31 JC |
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 | # | |
7 | from docutils import nodes | |
8 | from sphinx import addnodes | |
454f96f2 | 9 | from sphinx.environment import NoUri |
d74b0d31 JC |
10 | import re |
11 | ||
12 | # | |
13 | # Regex nastiness. Of course. | |
14 | # Try to identify "function()" that's not already marked up some | |
15 | # other way. Sphinx doesn't like a lot of stuff right after a | |
16 | # :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last | |
17 | # bit tries to restrict matches to things that won't create trouble. | |
18 | # | |
19 | RE_function = re.compile(r'([\w_][\w\d_]+\(\))') | |
20 | ||
21 | # | |
22 | # Many places in the docs refer to common system calls. It is | |
23 | # pointless to try to cross-reference them and, as has been known | |
24 | # to happen, somebody defining a function by these names can lead | |
25 | # to the creation of incorrect and confusing cross references. So | |
26 | # just don't even try with these names. | |
27 | # | |
11fec009 | 28 | Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap', |
82bf829b JN |
29 | 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl', |
30 | 'socket' ] | |
d74b0d31 JC |
31 | |
32 | # | |
33 | # Find all occurrences of function() and try to replace them with | |
34 | # appropriate cross references. | |
35 | # | |
36 | def markup_funcs(docname, app, node): | |
37 | cdom = app.env.domains['c'] | |
38 | t = node.astext() | |
39 | done = 0 | |
40 | repl = [ ] | |
41 | for m in RE_function.finditer(t): | |
42 | # | |
43 | # Include any text prior to function() as a normal text node. | |
44 | # | |
45 | if m.start() > done: | |
46 | repl.append(nodes.Text(t[done:m.start()])) | |
47 | # | |
48 | # Go through the dance of getting an xref out of the C domain | |
49 | # | |
50 | target = m.group(1)[:-2] | |
51 | target_text = nodes.Text(target + '()') | |
52 | xref = None | |
53 | if target not in Skipfuncs: | |
54 | lit_text = nodes.literal(classes=['xref', 'c', 'c-func']) | |
55 | lit_text += target_text | |
56 | pxref = addnodes.pending_xref('', refdomain = 'c', | |
57 | reftype = 'function', | |
58 | reftarget = target, modname = None, | |
59 | classname = None) | |
454f96f2 MCC |
60 | # |
61 | # XXX The Latex builder will throw NoUri exceptions here, | |
62 | # work around that by ignoring them. | |
63 | # | |
64 | try: | |
65 | xref = cdom.resolve_xref(app.env, docname, app.builder, | |
66 | 'function', target, pxref, lit_text) | |
67 | except NoUri: | |
68 | xref = None | |
d74b0d31 JC |
69 | # |
70 | # Toss the xref into the list if we got it; otherwise just put | |
71 | # the function text. | |
72 | # | |
73 | if xref: | |
74 | repl.append(xref) | |
75 | else: | |
76 | repl.append(target_text) | |
77 | done = m.end() | |
78 | if done < len(t): | |
79 | repl.append(nodes.Text(t[done:])) | |
80 | return repl | |
81 | ||
82 | def auto_markup(app, doctree, name): | |
83 | # | |
84 | # This loop could eventually be improved on. Someday maybe we | |
85 | # want a proper tree traversal with a lot of awareness of which | |
86 | # kinds of nodes to prune. But this works well for now. | |
87 | # | |
88 | # The nodes.literal test catches ``literal text``, its purpose is to | |
89 | # avoid adding cross-references to functions that have been explicitly | |
90 | # marked with cc:func:. | |
91 | # | |
92 | for para in doctree.traverse(nodes.paragraph): | |
93 | for node in para.traverse(nodes.Text): | |
94 | if not isinstance(node.parent, nodes.literal): | |
95 | node.parent.replace(node, markup_funcs(name, app, node)) | |
96 | ||
97 | def setup(app): | |
98 | app.connect('doctree-resolved', auto_markup) | |
99 | return { | |
100 | 'parallel_read_safe': True, | |
101 | 'parallel_write_safe': True, | |
102 | } |