Commit d18b0178 authored by Nícolas F. R. A. Prado's avatar Nícolas F. R. A. Prado Committed by Jonathan Corbet

docs: Add automatic cross-reference for documentation pages

Cross-referencing to other documentation pages is possible using the
:doc:`doc-file` directive from Sphinx.

Add automatic markup for references to other documentation pages in the
format Documentation/subfolder/doc-file.rst (the extension being
optional).
This requires that the path be passed all the way from the Documentation
folder, which can be longer than passing a relative path through the
:doc: directive, but avoids the markup, making the text cleaner when
read in plain text.
Signed-off-by: default avatarNícolas F. R. A. Prado <nfraprado@protonmail.com>
Link: https://lore.kernel.org/r/20200911133339.327721-3-nfraprado@protonmail.comSigned-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 1ac4cfb2
...@@ -24,6 +24,11 @@ from itertools import chain ...@@ -24,6 +24,11 @@ from itertools import chain
# #
RE_function = re.compile(r'(([\w_][\w\d_]+)\(\))') RE_function = re.compile(r'(([\w_][\w\d_]+)\(\))')
RE_type = re.compile(r'(struct|union|enum|typedef)\s+([\w_][\w\d_]+)') RE_type = re.compile(r'(struct|union|enum|typedef)\s+([\w_][\w\d_]+)')
#
# Detects a reference to a documentation page of the form Documentation/... with
# an optional extension
#
RE_doc = re.compile(r'Documentation(/[\w\-_/]+)(\.\w+)*')
# #
# Many places in the docs refer to common system calls. It is # Many places in the docs refer to common system calls. It is
...@@ -44,7 +49,8 @@ def markup_refs(docname, app, node): ...@@ -44,7 +49,8 @@ def markup_refs(docname, app, node):
# Associate each regex with the function that will markup its matches # Associate each regex with the function that will markup its matches
# #
markup_func = {RE_type: markup_c_ref, markup_func = {RE_type: markup_c_ref,
RE_function: markup_c_ref} RE_function: markup_c_ref,
RE_doc: markup_doc_ref}
match_iterators = [regex.finditer(t) for regex in markup_func] match_iterators = [regex.finditer(t) for regex in markup_func]
# #
# Sort all references by the starting position in text # Sort all references by the starting position in text
...@@ -108,6 +114,37 @@ def markup_c_ref(docname, app, match): ...@@ -108,6 +114,37 @@ def markup_c_ref(docname, app, match):
else: else:
return target_text return target_text
#
# Try to replace a documentation reference of the form Documentation/... with a
# cross reference to that page
#
def markup_doc_ref(docname, app, match):
stddom = app.env.domains['std']
#
# Go through the dance of getting an xref out of the std domain
#
target = match.group(1)
xref = None
pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'doc',
reftarget = target, modname = None,
classname = None, refexplicit = False)
#
# XXX The Latex builder will throw NoUri exceptions here,
# work around that by ignoring them.
#
try:
xref = stddom.resolve_xref(app.env, docname, app.builder, 'doc',
target, pxref, None)
except NoUri:
xref = None
#
# Return the xref if we got it; otherwise just return the plain text.
#
if xref:
return xref
else:
return nodes.Text(match.group(0))
def auto_markup(app, doctree, name): def auto_markup(app, doctree, name):
# #
# This loop could eventually be improved on. Someday maybe we # This loop could eventually be improved on. Someday maybe we
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment