diff options
Diffstat (limited to 'sphinx/roles.py')
| -rw-r--r-- | sphinx/roles.py | 35 |
1 files changed, 28 insertions, 7 deletions
diff --git a/sphinx/roles.py b/sphinx/roles.py index 0ea0ec48..b44868e6 100644 --- a/sphinx/roles.py +++ b/sphinx/roles.py @@ -18,7 +18,7 @@ from docutils.parsers.rst import roles from sphinx import addnodes from sphinx.locale import _ from sphinx.util import ws_re -from sphinx.util.nodes import split_explicit_title +from sphinx.util.nodes import split_explicit_title, process_index_entry generic_docroles = { @@ -139,16 +139,15 @@ class XRefRole(object): # methods that can be overwritten def process_link(self, env, refnode, has_explicit_title, title, target): - """ - Called after parsing title and target text, and creating the reference - node (given in *refnode*). This method can alter the reference node and - must return a new (or the same) ``(title, target)`` tuple. + """Called after parsing title and target text, and creating the + reference node (given in *refnode*). This method can alter the + reference node and must return a new (or the same) ``(title, target)`` + tuple. """ return title, ws_re.sub(' ', target) def result_nodes(self, document, env, node, is_ref): - """ - Called before returning the finished nodes. *node* is the reference + """Called before returning the finished nodes. *node* is the reference node if one was created (*is_ref* is then true), else the content node. This method can add other nodes and must return a ``(nodes, messages)`` tuple (the usual return value of a role function). @@ -269,6 +268,27 @@ def abbr_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): return [addnodes.abbreviation(abbr, abbr, explanation=expl)], [] +def index_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): + # create new reference target + env = inliner.document.settings.env + targetid = 'index-%s' % env.new_serialno('index') + targetnode = nodes.target('', '', ids=[targetid]) + # split text and target in role content + has_explicit_title, title, target = split_explicit_title(text) + title = utils.unescape(title) + target = utils.unescape(target) + # if an explicit target is given, we can process it as a full entry + if has_explicit_title: + entries = process_index_entry(target, targetid) + # otherwise we just create a "single" entry + else: + entries = [('single', target, targetid, target)] + indexnode = addnodes.index() + indexnode['entries'] = entries + textnode = nodes.Text(title, title) + return [indexnode, targetnode, textnode], [] + + specific_docroles = { # links to download references 'download': XRefRole(nodeclass=addnodes.download_reference), @@ -282,6 +302,7 @@ specific_docroles = { 'file': emph_literal_role, 'samp': emph_literal_role, 'abbr': abbr_role, + 'index': index_role, } for rolename, func in specific_docroles.iteritems(): |