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 2 uses the same :c:type role for struct, union, enum and typedef
27#
28RE_generic_type = re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_]\w+)',
29                             flags=re.ASCII)
30
31#
32# Sphinx 3 uses a different C role for each one of struct, union, enum and
33# typedef
34#
35RE_struct = re.compile(r'\b(struct)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
36RE_union = re.compile(r'\b(union)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
37RE_enum = re.compile(r'\b(enum)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
38RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=re.ASCII)
39
40#
41# Detects a reference to a documentation page of the form Documentation/... with
42# an optional extension
43#
44RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.(rst|txt)')
45RE_abi_file = re.compile(r'(\bDocumentation/ABI/[\w\-/]+)')
46RE_abi_symbol = re.compile(r'(\b/(sys|config|proc)/[\w\-/]+)')
47
48RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
49
50#
51# Reserved C words that we should skip when cross-referencing
52#
53Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ]
54
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 = {# Sphinx 2 only
154                 RE_function: 'c-func',
155                 RE_generic_type: 'c-type',
156                 # Sphinx 3+ only
157                 RE_struct: 'c-struct',
158                 RE_union: 'c-union',
159                 RE_enum: 'c-enum',
160                 RE_typedef: 'c-type',
161                 }
162    reftype_str = {# Sphinx 2 only
163                   RE_function: 'function',
164                   RE_generic_type: 'type',
165                   # Sphinx 3+ only
166                   RE_struct: 'struct',
167                   RE_union: 'union',
168                   RE_enum: 'enum',
169                   RE_typedef: 'type',
170                   }
171
172    base_target = match.group(2)
173    target_text = nodes.Text(match.group(0))
174    possible_targets = [base_target]
175    # Check if this document has a namespace, and if so, try
176    # cross-referencing inside it first.
177    if c_namespace:
178        possible_targets.insert(0, c_namespace + "." + base_target)
179
180    if base_target not in Skipnames:
181        for target in possible_targets:
182            if not (match.re == RE_function and target in Skipfuncs):
183                lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]])
184                lit_text += target_text
185                xref = add_and_resolve_xref(app, docname, 'c',
186                                            reftype_str[match.re], target,
187                                            contnode=lit_text)
188                if xref:
189                    return xref
190
191    return target_text
192
193#
194# Try to replace a documentation reference of the form Documentation/... with a
195# cross reference to that page
196#
197def markup_doc_ref(docname, app, match):
198    absolute = match.group(1)
199    target = match.group(2)
200    if absolute:
201       target = "/" + target
202
203    xref = add_and_resolve_xref(app, docname, 'std', 'doc', target)
204    if xref:
205        return xref
206    else:
207        return nodes.Text(match.group(0))
208
209#
210# Try to replace a documentation reference for ABI symbols and files
211# with a cross reference to that page
212#
213def markup_abi_ref(docname, app, match, warning=False):
214    kernel_abi = get_kernel_abi()
215
216    fname = match.group(1)
217    target = kernel_abi.xref(fname)
218
219    # Kernel ABI doesn't describe such file or symbol
220    if not target:
221        if warning:
222            kernel_abi.log.warning("%s not found", fname)
223        return nodes.Text(match.group(0))
224
225    xref = add_and_resolve_xref(app, docname, 'std', 'ref', target)
226    if xref:
227        return xref
228    else:
229        return nodes.Text(match.group(0))
230
231def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None):
232    #
233    # Go through the dance of getting an xref out of the corresponding domain
234    #
235    dom_obj = app.env.domains[domain]
236    pxref = addnodes.pending_xref('', refdomain = domain, reftype = reftype,
237                                  reftarget = target, modname = None,
238                                  classname = None, refexplicit = False)
239
240    #
241    # XXX The Latex builder will throw NoUri exceptions here,
242    # work around that by ignoring them.
243    #
244    try:
245        xref = dom_obj.resolve_xref(app.env, docname, app.builder, reftype,
246                                    target, pxref, contnode)
247    except NoUri:
248        xref = None
249
250    if xref:
251        return xref
252
253    return None
254
255#
256# Variant of markup_abi_ref() that warns whan a reference is not found
257#
258def markup_abi_file_ref(docname, app, match):
259    return markup_abi_ref(docname, app, match, warning=True)
260
261
262def get_c_namespace(app, docname):
263    source = app.env.doc2path(docname)
264    with open(source) as f:
265        for l in f:
266            match = RE_namespace.search(l)
267            if match:
268                return match.group(1)
269    return ''
270
271def markup_git(docname, app, match):
272    # While we could probably assume that we are running in a git
273    # repository, we can't know for sure, so let's just mechanically
274    # turn them into git.kernel.org links without checking their
275    # validity. (Maybe we can do something in the future to warn about
276    # these references if this is explicitly requested.)
277    text = match.group(0)
278    rev = match.group('rev')
279    return nodes.reference('', nodes.Text(text),
280        refuri=f'https://git.kernel.org/torvalds/c/{rev}')
281
282def auto_markup(app, doctree, name):
283    global c_namespace
284    c_namespace = get_c_namespace(app, name)
285    def text_but_not_a_reference(node):
286        # The nodes.literal test catches ``literal text``, its purpose is to
287        # avoid adding cross-references to functions that have been explicitly
288        # marked with cc:func:.
289        if not isinstance(node, nodes.Text) or isinstance(node.parent, nodes.literal):
290            return False
291
292        child_of_reference = False
293        parent = node.parent
294        while parent:
295            if isinstance(parent, nodes.Referential):
296                child_of_reference = True
297                break
298            parent = parent.parent
299        return not child_of_reference
300
301    #
302    # This loop could eventually be improved on.  Someday maybe we
303    # want a proper tree traversal with a lot of awareness of which
304    # kinds of nodes to prune.  But this works well for now.
305    #
306    for para in doctree.traverse(nodes.paragraph):
307        for node in para.traverse(condition=text_but_not_a_reference):
308            node.parent.replace(node, markup_refs(name, app, node))
309
310def setup(app):
311    app.connect('doctree-resolved', auto_markup)
312    return {
313        'parallel_read_safe': True,
314        'parallel_write_safe': True,
315        }
316