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