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 31# 32# Find all occurrences of function() and try to replace them with 33# appropriate cross references. 34# 35def markup_funcs(docname, app, node): 36 cdom = app.env.domains['c'] 37 t = node.astext() 38 done = 0 39 repl = [ ] 40 for m in RE_function.finditer(t): 41 # 42 # Include any text prior to function() as a normal text node. 43 # 44 if m.start() > done: 45 repl.append(nodes.Text(t[done:m.start()])) 46 # 47 # Go through the dance of getting an xref out of the C domain 48 # 49 target = m.group(1)[:-2] 50 target_text = nodes.Text(target + '()') 51 xref = None 52 if target not in Skipfuncs: 53 lit_text = nodes.literal(classes=['xref', 'c', 'c-func']) 54 lit_text += target_text 55 pxref = addnodes.pending_xref('', refdomain = 'c', 56 reftype = 'function', 57 reftarget = target, modname = None, 58 classname = None) 59 # 60 # XXX The Latex builder will throw NoUri exceptions here, 61 # work around that by ignoring them. 62 # 63 try: 64 xref = cdom.resolve_xref(app.env, docname, app.builder, 65 'function', target, pxref, lit_text) 66 except NoUri: 67 xref = None 68 # 69 # Toss the xref into the list if we got it; otherwise just put 70 # the function text. 71 # 72 if xref: 73 repl.append(xref) 74 else: 75 repl.append(target_text) 76 done = m.end() 77 if done < len(t): 78 repl.append(nodes.Text(t[done:])) 79 return repl 80 81def auto_markup(app, doctree, name): 82 # 83 # This loop could eventually be improved on. Someday maybe we 84 # want a proper tree traversal with a lot of awareness of which 85 # kinds of nodes to prune. But this works well for now. 86 # 87 # The nodes.literal test catches ``literal text``, its purpose is to 88 # avoid adding cross-references to functions that have been explicitly 89 # marked with cc:func:. 90 # 91 for para in doctree.traverse(nodes.paragraph): 92 for node in para.traverse(nodes.Text): 93 if not isinstance(node.parent, nodes.literal): 94 node.parent.replace(node, markup_funcs(name, app, node)) 95 96def setup(app): 97 app.connect('doctree-resolved', auto_markup) 98 return { 99 'parallel_read_safe': True, 100 'parallel_write_safe': True, 101 } 102