diff options
Diffstat (limited to 'Documentation/sphinx')
| -rw-r--r-- | Documentation/sphinx/automarkup.py | 97 |
1 files changed, 55 insertions, 42 deletions
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index 272eb2bdfab1..6c8e8475eddb 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -36,65 +36,78 @@ Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap', 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl', 'socket' ] -# -# Find all occurrences of C references (function() and struct/union/enum/typedef -# type_name) and try to replace them with appropriate cross references. -# -def markup_c_refs(docname, app, node): - class_str = {RE_function: 'c-func', RE_type: 'c-type'} - reftype_str = {RE_function: 'function', RE_type: 'type'} - - cdom = app.env.domains['c'] +def markup_refs(docname, app, node): t = node.astext() done = 0 repl = [ ] # - # Sort all C references by the starting position in text + # Associate each regex with the function that will markup its matches + # + markup_func = {RE_type: markup_c_ref, + RE_function: markup_c_ref} + match_iterators = [regex.finditer(t) for regex in markup_func] # - sorted_matches = sorted(chain(RE_type.finditer(t), RE_function.finditer(t)), - key=lambda m: m.start()) + # Sort all references by the starting position in text + # + sorted_matches = sorted(chain(*match_iterators), key=lambda m: m.start()) for m in sorted_matches: # # Include any text prior to match as a normal text node. # if m.start() > done: repl.append(nodes.Text(t[done:m.start()])) + # - # Go through the dance of getting an xref out of the C domain - # - target = m.group(2) - target_text = nodes.Text(m.group(0)) - xref = None - if not (m.re == RE_function and target in Skipfuncs): - lit_text = nodes.literal(classes=['xref', 'c', class_str[m.re]]) - lit_text += target_text - pxref = addnodes.pending_xref('', refdomain = 'c', - reftype = reftype_str[m.re], - reftarget = target, modname = None, - classname = None) - # - # XXX The Latex builder will throw NoUri exceptions here, - # work around that by ignoring them. - # - try: - xref = cdom.resolve_xref(app.env, docname, app.builder, - reftype_str[m.re], target, pxref, - lit_text) - except NoUri: - xref = None - # - # Toss the xref into the list if we got it; otherwise just put - # the function text. + # Call the function associated with the regex that matched this text and + # append its return to the text # - if xref: - repl.append(xref) - else: - repl.append(target_text) + repl.append(markup_func[m.re](docname, app, m)) + done = m.end() if done < len(t): repl.append(nodes.Text(t[done:])) return repl +# +# Try to replace a C reference (function() or struct/union/enum/typedef +# type_name) with an appropriate cross reference. +# +def markup_c_ref(docname, app, match): + class_str = {RE_function: 'c-func', RE_type: 'c-type'} + reftype_str = {RE_function: 'function', RE_type: 'type'} + + cdom = app.env.domains['c'] + # + # Go through the dance of getting an xref out of the C domain + # + target = match.group(2) + target_text = nodes.Text(match.group(0)) + xref = None + if not (match.re == RE_function and target in Skipfuncs): + lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]]) + lit_text += target_text + pxref = addnodes.pending_xref('', refdomain = 'c', + reftype = reftype_str[match.re], + reftarget = target, modname = None, + classname = None) + # + # XXX The Latex builder will throw NoUri exceptions here, + # work around that by ignoring them. + # + try: + xref = cdom.resolve_xref(app.env, docname, app.builder, + reftype_str[match.re], target, pxref, + lit_text) + except NoUri: + xref = None + # + # Return the xref if we got it; otherwise just return the plain text. + # + if xref: + return xref + else: + return target_text + def auto_markup(app, doctree, name): # # This loop could eventually be improved on. Someday maybe we @@ -108,7 +121,7 @@ def auto_markup(app, doctree, name): for para in doctree.traverse(nodes.paragraph): for node in para.traverse(nodes.Text): if not isinstance(node.parent, nodes.literal): - node.parent.replace(node, markup_c_refs(name, app, node)) + node.parent.replace(node, markup_refs(name, app, node)) def setup(app): app.connect('doctree-resolved', auto_markup) |