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        }