diff options
author | NĂcolas F. R. A. Prado <nfraprado@protonmail.com> | 2020-09-11 16:34:39 +0300 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2020-09-16 20:09:51 +0300 |
commit | d18b01789ae5abba2ce8dd23c984926eca3925a9 (patch) | |
tree | 30a4208d0eb4f70b34f87eb3e60183718676a303 /Documentation/sphinx/automarkup.py | |
parent | 1ac4cfb2ce03e1a7382c64fe73c9e16c0acc20db (diff) | |
download | linux-d18b01789ae5abba2ce8dd23c984926eca3925a9.tar.xz |
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/automarkup.py')
-rw-r--r-- | Documentation/sphinx/automarkup.py | 39 |
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 |