[PATCH] common: Show page references after internal links
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue Aug 13 05:23:06 UTC 2019
The custom RTEMS extension produced quite verbose references like
"Chapter 3 - Section 7 - Bla blub". This may distract the reading flow.
Use a standard Sphinx option to show page references instead, e.g. "Bla
blub (page 11)". This has some value for printed out documents.
---
common/conf.py | 3 +--
common/rtemsext.py | 57 ------------------------------------------------------
2 files changed, 1 insertion(+), 59 deletions(-)
delete mode 100644 common/rtemsext.py
diff --git a/common/conf.py b/common/conf.py
index 821f913..fe44640 100644
--- a/common/conf.py
+++ b/common/conf.py
@@ -6,7 +6,6 @@ extensions = [
"sphinx.ext.intersphinx",
"sphinx.ext.mathjax",
"sphinxcontrib.bibtex",
- "rtemsext",
"rtemsdomain",
]
@@ -196,7 +195,7 @@ latex_use_modindex = False
#latex_logo = None
# If true, show page references after internal links.
-latex_show_pagerefs = False
+latex_show_pagerefs = True
# If true, show URL addresses after external links.
#latex_show_urls=True
diff --git a/common/rtemsext.py b/common/rtemsext.py
deleted file mode 100644
index 85b989e..0000000
--- a/common/rtemsext.py
+++ /dev/null
@@ -1,57 +0,0 @@
-from docutils import nodes
-import sphinx.domains.std
-
-# Borrowed from: http://stackoverflow.com/questions/13848328/sphinx-references-to-other-sections-containing-section-number-and-section-title
-class CustomStandardDomain(sphinx.domains.std.StandardDomain):
-
- def __init__(self, env):
- env.settings['footnote_references'] = 'superscript'
- sphinx.domains.std.StandardDomain.__init__(self, env)
-
- def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
- res = super(CustomStandardDomain, self).resolve_xref(env, fromdocname, builder, typ, target, node, contnode)
-
- if res is None:
- return res
-
- if typ == 'ref' and not node['refexplicit']:
- docname, labelid, sectname = self.data['labels'].get(target, ('','',''))
- res['refdocname'] = docname
-
- return res
-
-def doctree_resolved(app, doctree, docname):
- secnums = app.builder.env.toc_secnumbers
- for node in doctree.traverse(nodes.reference):
- if 'refdocname' in node:
- refdocname = node['refdocname']
- if refdocname in secnums:
- secnum = secnums[refdocname]
- emphnode = node.children[0]
- textnode = emphnode.children[0]
-
- toclist = app.builder.env.tocs[refdocname]
- anchorname = None
- for refnode in toclist.traverse(nodes.reference):
- if refnode.astext() == textnode.astext():
- anchorname = refnode['anchorname']
- if anchorname is None:
- continue
- sec_number = secnum[anchorname]
- chapter = sec_number[0]
- section = None
-
- if len(sec_number) > 1:
- section = ".".join(map(str, sec_number[1:]))
-
- if section:
- node.replace(emphnode, nodes.Text("Chapter %s Section %s - %s" % (chapter, section, textnode)))
- else:
- node.replace(emphnode, nodes.Text("Chapter %s - %s" % (chapter, textnode)))
-
-def setup(app):
- app.override_domain(CustomStandardDomain)
- app.connect('doctree-resolved', doctree_resolved)
-
- return {'version': "1.0", 'parallel_read_safe': True}
-
--
2.16.4
More information about the devel
mailing list