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
8from sphinx import addnodes
9from sphinx.environment import NoUri
10import 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#
19RE_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#
28Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap',
29              'select', 'poll', 'fork', 'execve', 'clone', 'ioctl',
30              'socket' ]
31
32#
33# Find all occurrences of function() and try to replace them with
34# appropriate cross references.
35#
36def 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)
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
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
82def 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
97def setup(app):
98    app.connect('doctree-resolved', auto_markup)
99    return {
100        'parallel_read_safe': True,
101        'parallel_write_safe': True,
102        }
103