docutils.parsers.rst.roles

module documentation

This module defines standard interpreted text role functions, a registry for interpreted text roles, and an API for adding to and retrieving from the registry. See also Creating reStructuredText Interpreted Text Roles.

The interface for interpreted role functions is as follows:

def role_fn(name, rawtext, text, lineno, inliner,
            options={}, content=[]):
    code...

# Set function attributes for customization:
role_fn.options = ...
role_fn.content = ...

Parameters:

name is the local name of the interpreted text role, the role name actually used in the document.
rawtext is a string containing the entire interpreted text construct. Return it as a problematic node linked to a system message if there is a problem.
text is the interpreted text content, with backslash escapes converted to nulls (\).
lineno is the line number where the text block containing the interpreted text begins.
inliner is the Inliner object that called the role function. It defines the following useful attributes: reporter, problematic, memo, parent, document.
options: A dictionary of directive options for customization, to be interpreted by the role function. Used for additional attributes for the generated elements and other functionality.
content: A list of strings, the directive content for customization ("role" directive). To be interpreted by the role function.

Function attributes for customization, interpreted by the "role" directive:

options: A dictionary, mapping known option names to conversion functions such as int or float. None or an empty dict implies no options to parse. Several directive option conversion functions are defined in the directives module.

All role functions implicitly support the "class" option, unless disabled with an explicit {'class': None}.
content: A boolean; true if content is allowed. Client code must handle the case where content is required but not supplied (an empty content list will be supplied).

Note that unlike directives, the "arguments" function attribute is not supported for role customization. Directive arguments are handled by the "role" directive itself.

Interpreted role functions return a tuple of two values:

A list of nodes which will be inserted into the document tree at the point where the interpreted role was encountered (can be an empty list).
A list of system messages, which will be inserted into the document tree immediately after the end of the current inline block (can also be empty).

Class	`CustomRole`	Wrapper for custom interpreted text roles.
Class	`GenericRole`	Generic interpreted text role.
Function	`code_role`	Undocumented
Function	`generic_custom_role`	Base for custom roles if no other base role is specified.
Function	`math_role`	Undocumented
Function	`pep_reference_role`	Undocumented
Function	`raw_role`	Undocumented
Function	`register_canonical_role`	Register an interpreted text role by its canonical name.
Function	`register_generic_role`	For roles which simply wrap a given `node_class` around the text.
Function	`register_local_role`	Register an interpreted text role by its local or language-dependent name.
Function	`rfc_reference_role`	Undocumented
Function	`role`	Locate and return a role function from its language-dependent name, along with a list of system messages.
Function	`set_classes`	Auxiliary function to set options['classes'] and delete options['class'].
Function	`set_implicit_options`	Add customization options to role functions, unless explicitly set or disabled.
Function	`unimplemented_role`	Undocumented
Constant	`DEFAULT_INTERPRETED_ROLE`	The canonical name of the default interpreted role.
Variable	`_role_registry`	Mapping of canonical role names to role functions.
Variable	`_roles`	Mapping of local or language-dependent interpreted text role names to role functions.

def code_role(role, rawtext, text, lineno, inliner, options={}, content=[]):

Undocumented

def generic_custom_role(role, rawtext, text, lineno, inliner, options={}, content=[]):

Base for custom roles if no other base role is specified.

def math_role(role, rawtext, text, lineno, inliner, options={}, content=[]):

Undocumented

def pep_reference_role(role, rawtext, text, lineno, inliner, options={}, content=[]):

Undocumented

def raw_role(role, rawtext, text, lineno, inliner, options={}, content=[]):

Undocumented

def register_canonical_role(name, role_fn):

Parameters
name	The canonical name of the interpreted role.
role_fn	The role function. See the module docstring.

def register_generic_role(canonical_name, node_class):

For roles which simply wrap a given node_class around the text.

def register_local_role(name, role_fn):

Parameters
name	The local or language-dependent name of the interpreted role.
role_fn	The role function. See the module docstring.

def rfc_reference_role(role, rawtext, text, lineno, inliner, options={}, content=[]):

Undocumented

def role(role_name, language_module, lineno, reporter):

Locate and return a role function from its language-dependent name, along with a list of system messages.

If the role is not found in the current language, check English. Return a 2-tuple: role function (None if the named role cannot be found) and a list of system messages.

def set_classes(options):

Auxiliary function to set options['classes'] and delete options['class'].

def set_implicit_options(role_fn):

Add customization options to role functions, unless explicitly set or disabled.

def unimplemented_role(role, rawtext, text, lineno, inliner, options=None, content=None):

Undocumented

DEFAULT_INTERPRETED_ROLE: str =

The canonical name of the default interpreted role.

This role is used when no role is specified for a piece of interpreted text.

Value

'title-reference'

_role_registry: dict =

Mapping of canonical role names to role functions.

Language-dependent role names are defined in the language subpackage.

_roles: dict =

Mapping of local or language-dependent interpreted text role names to role functions.