sphinx.roles.XRefRole

class documentation

class XRefRole(ReferenceRole): (source)

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 <target>`. * 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`	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.
Method	`result_nodes`	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).
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:

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

Inherited from SphinxRole (via ReferenceRole):

Method	`get_location`	Get current location info for logging.
Method	`get_source_info`	Undocumented
Method	`set_source_info`	Undocumented
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 :class:`.Config` object.
Property	`env`	Reference to the :class:`.BuildEnvironment` object.

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

Undocumented

Parameters
fix_parens:`bool`	Undocumented
lowercase:`bool`	Undocumented
nodeclass:`type[Element]\|None`	Undocumented
innernodeclass:`type[TextElement]\|None`	Undocumented
warn_dangling:`bool`	Undocumented

def create_non_xref_node(self): (source) ¶

Undocumented

Returns
`tuple[list[Node], list[system_message]]`	Undocumented

def create_xref_node(self): (source) ¶

Undocumented

Returns
`tuple[list[Node], list[system_message]]`	Undocumented

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

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): (source) ¶

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