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