[rtems-docs commit] common: Show page references after internal links

Sebastian Huber sebh at rtems.org
Wed Aug 14 05:27:53 UTC 2019


Module:    rtems-docs
Branch:    master
Commit:    5d7921bebc1d01bdd1b1114829d97cd8c3ac1368
Changeset: http://git.rtems.org/rtems-docs/commit/?id=5d7921bebc1d01bdd1b1114829d97cd8c3ac1368

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Tue Aug 13 07:18:59 2019 +0200

common: Show page references after internal links

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(-)

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




More information about the vc mailing list