summaryrefslogtreecommitdiff
path: root/Documentation/sphinx
diff options
context:
space:
mode:
authorNĂ­colas F. R. A. Prado <nfraprado@protonmail.com>2020-09-11 13:34:39 +0000
committerJonathan Corbet <corbet@lwn.net>2020-09-16 11:09:51 -0600
commitd18b01789ae5abba2ce8dd23c984926eca3925a9 (patch)
tree30a4208d0eb4f70b34f87eb3e60183718676a303 /Documentation/sphinx
parent1ac4cfb2ce03e1a7382c64fe73c9e16c0acc20db (diff)
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: NĂ­colas F. R. A. Prado <nfraprado@protonmail.com> Link: https://lore.kernel.org/r/20200911133339.327721-3-nfraprado@protonmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/sphinx')
-rw-r--r--Documentation/sphinx/automarkup.py39
1 files changed, 38 insertions, 1 deletions
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 6c8e8475eddb..a1b0f554cd82 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -24,6 +24,11 @@ from itertools import chain
#
RE_function = re.compile(r'(([\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
@@ -44,7 +49,8 @@ def markup_refs(docname, app, node):
# Associate each regex with the function that will markup its matches
#
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]
#
# Sort all references by the starting position in text
@@ -108,6 +114,37 @@ def markup_c_ref(docname, app, match):
else:
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):
#
# This loop could eventually be improved on. Someday maybe we