lkml.org 
[lkml]   [2020]   [Sep]   [11]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
Date
From
Subject[PATCH 2/3] 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>
---
Documentation/sphinx/automarkup.py | 39 +++++++++++++++++++++++++++++-
1 file changed, 38 insertions(+), 1 deletion(-)

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
--
2.28.0

\
 
 \ /
  Last update: 2020-09-11 19:10    [W:0.054 / U:3.212 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site