Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-12-14 15:13:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Allow multiple automarkup functions

Browse Source 
The automarkup script previously matched expressions and substituted
them with markup to enable automatic cross-reference all in the same
function.

Split the expression matching iteration and the markup substitution into
different functions to make it easier to add new regular expressions and
functions to treat each of them.

Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
Link: https://lore.kernel.org/r/20200911133339.327721-2-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Nícolas F. R. A. Prado 2020-09-11 13:34:33 +00:00 committed by Jonathan Corbet
parent 78ff97ebd4
commit 1ac4cfb2ce
1 changed files with 55 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
Documentation/sphinx/automarkup.py
View File

@ -36,40 +36,58 @@ 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
#
sorted_matches = sorted(chain(RE_type.finditer(t), RE_function.finditer(t)),
key=lambda m: m.start())
markup_func = {RE_type: markup_c_ref,
RE_function: markup_c_ref}
match_iterators = [regex.finditer(t) for regex in markup_func]
#
# 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()]))
#
# Call the function associated with the regex that matched this text and
# append its return to the 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 = m.group(2)
target_text = nodes.Text(m.group(0))
target = match.group(2)
target_text = nodes.Text(match.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]])
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[m.re],
reftype = reftype_str[match.re],
reftarget = target, modname = None,
classname = None)
#
@ -78,22 +96,17 @@ def markup_c_refs(docname, app, node):
#
try:
xref = cdom.resolve_xref(app.env, docname, app.builder,
reftype_str[m.re], target, pxref,
reftype_str[match.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.
# Return the xref if we got it; otherwise just return the plain text.
#
if xref:
repl.append(xref)
return xref
else:
repl.append(target_text)
done = m.end()
if done < len(t):
repl.append(nodes.Text(t[done:]))
return repl
return target_text
def auto_markup(app, doctree, name):
#
@ -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)