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    cdom = app.env.domains['c']
132    #
133    # Go through the dance of getting an xref out of the C domain
134    #
135    base_target = match.group(2)
136    target_text = nodes.Text(match.group(0))
137    xref = None
138    possible_targets = [base_target]
139    # Check if this document has a namespace, and if so, try
140    # cross-referencing inside it first.
141    if c_namespace:
142        possible_targets.insert(0, c_namespace + "." + base_target)
143
144    if base_target not in Skipnames:
145        for target in possible_targets:
146            if (target not in Skipfuncs) and not failure_seen(target):
147                lit_text = nodes.literal(classes=['xref', 'c', 'c-func'])
148                lit_text += target_text
149                pxref = addnodes.pending_xref('', refdomain = 'c',
150                                              reftype = 'function',
151                                              reftarget = target,
152                                              modname = None,
153                                              classname = None)
154                #
155                # XXX The Latex builder will throw NoUri exceptions here,
156                # work around that by ignoring them.
157                #
158                try:
159                    xref = cdom.resolve_xref(app.env, docname, app.builder,
160                                             'function', target, pxref,
161                                             lit_text)
162                except NoUri:
163                    xref = None
164
165                if xref:
166                    return xref
167                note_failure(target)
168
169    return target_text
170
171def markup_c_ref(docname, app, match):
172    class_str = {# Sphinx 2 only
173                 RE_function: 'c-func',
174                 RE_generic_type: 'c-type',
175                 # Sphinx 3+ only
176                 RE_struct: 'c-struct',
177                 RE_union: 'c-union',
178                 RE_enum: 'c-enum',
179                 RE_typedef: 'c-type',
180                 }
181    reftype_str = {# Sphinx 2 only
182                   RE_function: 'function',
183                   RE_generic_type: 'type',
184                   # Sphinx 3+ only
185                   RE_struct: 'struct',
186                   RE_union: 'union',
187                   RE_enum: 'enum',
188                   RE_typedef: 'type',
189                   }
190
191    cdom = app.env.domains['c']
192    #
193    # Go through the dance of getting an xref out of the C domain
194    #
195    base_target = match.group(2)
196    target_text = nodes.Text(match.group(0))
197    xref = None
198    possible_targets = [base_target]
199    # Check if this document has a namespace, and if so, try
200    # cross-referencing inside it first.
201    if c_namespace:
202        possible_targets.insert(0, c_namespace + "." + base_target)
203
204    if base_target not in Skipnames:
205        for target in possible_targets:
206            if not (match.re == RE_function and target in Skipfuncs):
207                lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]])
208                lit_text += target_text
209                pxref = addnodes.pending_xref('', refdomain = 'c',
210                                              reftype = reftype_str[match.re],
211                                              reftarget = target, modname = None,
212                                              classname = None)
213                #
214                # XXX The Latex builder will throw NoUri exceptions here,
215                # work around that by ignoring them.
216                #
217                try:
218                    xref = cdom.resolve_xref(app.env, docname, app.builder,
219                                             reftype_str[match.re], target, pxref,
220                                             lit_text)
221                except NoUri:
222                    xref = None
223
224                if xref:
225                    return xref
226
227    return target_text
228
229#
230# Try to replace a documentation reference of the form Documentation/... with a
231# cross reference to that page
232#
233def markup_doc_ref(docname, app, match):
234    stddom = app.env.domains['std']
235    #
236    # Go through the dance of getting an xref out of the std domain
237    #
238    absolute = match.group(1)
239    target = match.group(2)
240    if absolute:
241       target = "/" + target
242    xref = None
243    pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'doc',
244                                  reftarget = target, modname = None,
245                                  classname = None, refexplicit = False)
246    #
247    # XXX The Latex builder will throw NoUri exceptions here,
248    # work around that by ignoring them.
249    #
250    try:
251        xref = stddom.resolve_xref(app.env, docname, app.builder, 'doc',
252                                   target, pxref, None)
253    except NoUri:
254        xref = None
255    #
256    # Return the xref if we got it; otherwise just return the plain text.
257    #
258    if xref:
259        return xref
260    else:
261        return nodes.Text(match.group(0))
262
263#
264# Try to replace a documentation reference for ABI symbols and files
265# with a cross reference to that page
266#
267def markup_abi_ref(docname, app, match, warning=False):
268    stddom = app.env.domains['std']
269    #
270    # Go through the dance of getting an xref out of the std domain
271    #
272    kernel_abi = get_kernel_abi()
273
274    fname = match.group(1)
275    target = kernel_abi.xref(fname)
276
277    # Kernel ABI doesn't describe such file or symbol
278    if not target:
279        if warning:
280            kernel_abi.log.warning("%s not found", fname)
281        return nodes.Text(match.group(0))
282
283    pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'ref',
284                                  reftarget = target, modname = None,
285                                  classname = None, refexplicit = False)
286
287    #
288    # XXX The Latex builder will throw NoUri exceptions here,
289    # work around that by ignoring them.
290    #
291    try:
292        xref = stddom.resolve_xref(app.env, docname, app.builder, 'ref',
293                                   target, pxref, None)
294    except NoUri:
295        xref = None
296    #
297    # Return the xref if we got it; otherwise just return the plain text.
298    #
299    if xref:
300        return xref
301    else:
302        return nodes.Text(match.group(0))
303
304#
305# Variant of markup_abi_ref() that warns whan a reference is not found
306#
307def markup_abi_file_ref(docname, app, match):
308    return markup_abi_ref(docname, app, match, warning=True)
309
310
311def get_c_namespace(app, docname):
312    source = app.env.doc2path(docname)
313    with open(source) as f:
314        for l in f:
315            match = RE_namespace.search(l)
316            if match:
317                return match.group(1)
318    return ''
319
320def markup_git(docname, app, match):
321    # While we could probably assume that we are running in a git
322    # repository, we can't know for sure, so let's just mechanically
323    # turn them into git.kernel.org links without checking their
324    # validity. (Maybe we can do something in the future to warn about
325    # these references if this is explicitly requested.)
326    text = match.group(0)
327    rev = match.group('rev')
328    return nodes.reference('', nodes.Text(text),
329        refuri=f'https://git.kernel.org/torvalds/c/{rev}')
330
331def auto_markup(app, doctree, name):
332    global c_namespace
333    c_namespace = get_c_namespace(app, name)
334    def text_but_not_a_reference(node):
335        # The nodes.literal test catches ``literal text``, its purpose is to
336        # avoid adding cross-references to functions that have been explicitly
337        # marked with cc:func:.
338        if not isinstance(node, nodes.Text) or isinstance(node.parent, nodes.literal):
339            return False
340
341        child_of_reference = False
342        parent = node.parent
343        while parent:
344            if isinstance(parent, nodes.Referential):
345                child_of_reference = True
346                break
347            parent = parent.parent
348        return not child_of_reference
349
350    #
351    # This loop could eventually be improved on.  Someday maybe we
352    # want a proper tree traversal with a lot of awareness of which
353    # kinds of nodes to prune.  But this works well for now.
354    #
355    for para in doctree.traverse(nodes.paragraph):
356        for node in para.traverse(condition=text_but_not_a_reference):
357            node.parent.replace(node, markup_refs(name, app, node))
358
359def setup(app):
360    app.connect('doctree-resolved', auto_markup)
361    return {
362        'parallel_read_safe': True,
363        'parallel_write_safe': True,
364        }
365