sphinx.roles.XRefRole

class documentation

class XRefRole(ReferenceRole):

Known subclasses: sphinx.domains.c.CXRefRole, sphinx.domains.cpp.CPPXRefRole, sphinx.domains.javascript.JSXRefRole, sphinx.domains.math.MathReferenceRole, sphinx.domains.python.PyXRefRole, sphinx.domains.std.EnvVarXRefRole, sphinx.domains.std.OptionXRefRole, sphinx.domains.std.TokenXRefRole, sphinx.roles.AnyXRefRole

View In Hierarchy

A generic cross-referencing role. To create a callable that can be used as a role function, create an instance of this class.

The general features of this role are:

Automatic creation of a reference and a content node.
Optional separation of title and target with title.
The implementation is a class rather than a function to make customization easier.

Customization can be done in two ways:

Supplying constructor parameters: * fix_parens to normalize parentheses (strip from target, and add to

title if configured)
- lowercase to lowercase the target
- nodeclass and innernodeclass select the node classes for the reference and the content node
Subclassing and overwriting process_link() and/or result_nodes().

Method	`__init__`	Undocumented
Method	`create_non_xref_node`	Undocumented
Method	`create_xref_node`	Undocumented
Method	`process_link`	No summary
Method	`result_nodes`	No summary
Method	`run`	Undocumented
Method	`update_title_and_target`	Undocumented
Instance Variable	`classes`	Undocumented
Instance Variable	`fix_parens`	Undocumented
Instance Variable	`has_explicit_title`	Undocumented
Instance Variable	`innernodeclass`	Undocumented
Instance Variable	`lowercase`	Undocumented
Instance Variable	`nodeclass`	Undocumented
Instance Variable	`refdomain`	Undocumented
Instance Variable	`reftype`	Undocumented
Instance Variable	`warn_dangling`	Undocumented

Inherited from ReferenceRole:

Instance Variable	`disabled`	Undocumented
Instance Variable	`target`	Undocumented
Instance Variable	`title`	Undocumented
Method	`__call__`	Undocumented
Class Variable	`explicit_title_re`	Undocumented

Inherited from SphinxRole (via ReferenceRole):

Method	`get_location`	Get current location info for logging.
Instance Variable	`content`	Undocumented
Instance Variable	`inliner`	Undocumented
Instance Variable	`lineno`	Undocumented
Instance Variable	`name`	Undocumented
Instance Variable	`options`	Undocumented
Instance Variable	`rawtext`	Undocumented
Instance Variable	`text`	Undocumented
Property	`config`	Reference to the `.Config` object.
Property	`env`	Reference to the `.BuildEnvironment` object.
Method	`get_source_info`	Undocumented
Method	`set_source_info`	Undocumented

def __init__(self, fix_parens=False, lowercase=False, nodeclass=None, innernodeclass=None, warn_dangling=False):

Undocumented

Parameters
fix_parens:`bool`	Undocumented
lowercase:`bool`	Undocumented
nodeclass:`Type[Element]`	Undocumented
innernodeclass:`Type[TextElement]`	Undocumented
warn_dangling:`bool`	Undocumented

def create_non_xref_node(self):

Undocumented

Returns
`Tuple[List[Node], List[system_message]]`	Undocumented

def create_xref_node(self):

Undocumented

Returns
`Tuple[List[Node], List[system_message]]`	Undocumented

def process_link(self, env, refnode, has_explicit_title, title, target):

overridden in sphinx.domains.c.CXRefRole, sphinx.domains.cpp.CPPXRefRole, sphinx.domains.javascript.JSXRefRole, sphinx.domains.python.PyXRefRole, sphinx.domains.std.OptionXRefRole, sphinx.domains.std.TokenXRefRole, sphinx.roles.AnyXRefRole

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.

Parameters
env:`BuildEnvironment`	Undocumented
refnode:`Element`	Undocumented
has_explicit_title:`bool`	Undocumented
title:`str`	Undocumented
target:`str`	Undocumented
Returns
`Tuple[str, str]`	Undocumented

def result_nodes(self, document, env, node, is_ref):

overridden in sphinx.domains.math.MathReferenceRole, sphinx.domains.std.EnvVarXRefRole

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

Parameters
document:`nodes.document`	Undocumented
env:`BuildEnvironment`	Undocumented
node:`Element`	Undocumented
is_ref:`bool`	Undocumented
Returns
`Tuple[List[Node], List[system_message]]`	Undocumented

def run(self):

overrides sphinx.util.docutils.SphinxRole.run

overridden in sphinx.domains.c.CXRefRole

Undocumented

Returns
`Tuple[List[Node], List[system_message]]`	Undocumented

def update_title_and_target(self, title, target):

Undocumented

Parameters
title:`str`	Undocumented
target:`str`	Undocumented
Returns
`Tuple[str, str]`	Undocumented

classes =

Undocumented

fix_parens =

Undocumented

has_explicit_title: bool =

overrides sphinx.util.docutils.ReferenceRole.has_explicit_title

Undocumented

innernodeclass =

Undocumented

lowercase =

Undocumented

nodeclass =

Undocumented

refdomain =

Undocumented

reftype =

Undocumented

warn_dangling =

Undocumented