rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-31 08:01:24 +08:00
Code Issues Packages Projects Releases Wiki Activity

common: Show page references after internal links

Browse Source 
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.
This commit is contained in:
Sebastian Huber 2019-08-13 07:18:59 +02:00
parent 29e0ac3799
commit 5d7921bebc
2 changed files with 1 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
common/conf.py
View File

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

57
common/rtemsext.py
View File

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