Creating reStructuredText Interpreted Text Roles

Define the Role Function

The role function creates and returns inline elements (nodes) and does any additional processing required. Its signature is as follows:

def role_fn(name, rawtext, text, lineno, inliner,
            options=None, content=None):
    code...

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

Function attributes are described below (see Specify Role Function Options and Content). The role function parameters are as follows:

• name: The local name of the interpreted role, the role name actually used in the document.

• rawtext: A string containing the entire interpreted text input, including the role and markup. Return it as a problematic node linked to a system message if a problem is encountered.

• text: The interpreted text content.

• lineno: The line number where the text block containing the interpreted text begins.

• inliner: The docutils.parsers.rst.states.Inliner object that called role_fn. It contains the several attributes useful for error reporting and document tree access.

• options: A dictionary of directive options for customization (from the "role" directive), 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 (from the "role" directive). To be interpreted by the role function.

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 block (can also be empty).

Specify Role Function Options and Content

Function attributes are for customization, and are interpreted by the "role" directive. If unspecified, role function attributes are assumed to have the value None. Two function attributes are recognized:

• options: The option specification. All role functions implicitly support the "class" option, unless disabled with an explicit {'class': None}.

  An option specification must be defined detailing the options available to the "role" directive. An option spec is a mapping of option name to conversion function; conversion functions are applied to each option value to check validity and convert them to the expected type. Python's built-in conversion functions are often usable for this, such as int, float, and bool (included in Python from version 2.2.1). Other useful conversion functions are included in the docutils.parsers.rst.directives package. For further details, see Creating reStructuredText Directives.

• content: A boolean; true if "role" directive content is allowed. Role functions must handle the case where content is required but not supplied (an empty content list will be supplied).

  As of this writing, no roles accept directive content.

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

Register the Role

If the role is a general-use addition to the Docutils core, it must be registered with the parser and language mappings added:

1. Register the new role using the canonical name:

   from docutils.parsers.rst import roles
   roles.register_canonical_role(name, role_function)

   This code is normally placed immediately after the definition of the role function.

2. Add an entry to the roles dictionary in docutils/parsers/rst/languages/en.py for the role, mapping the English name to the canonical name (both lowercase). Usually the English name and the canonical name are the same. Abbreviations and other aliases may also be added here.

3. Update all the other language modules as well. For languages in which you are proficient, please add translations. For other languages, add the English role name plus "(translation required)".

If the role is application-specific, use the register_local_role function:

from docutils.parsers.rst import roles
roles.register_local_role(name, role_function)

Examples

For the most direct and accurate information, "Use the Source, Luke!". All standard roles are documented in reStructuredText Interpreted Text Roles, and the source code implementing them is located in the docutils/parsers/rst/roles.py module. Several representative roles are described below.

register_generic_role('emphasis', nodes.emphasis)

See :RFC:`2822` for information about email headers.

See `RFC 2822`__ for information about email headers.

__ http://www.faqs.org/rfcs/rfc2822.html

def rfc_reference_role(role, rawtext, text, lineno, inliner,
                       options=None, content=None):
    if "#" in text:
        rfcnum, section = utils.unescape(text).split("#", 1)
    else:
        rfcnum, section  = utils.unescape(text), None
    try:
        rfcnum = int(rfcnum)
        if rfcnum < 1:
            raise ValueError
    except ValueError:
        msg = inliner.reporter.error(
            'RFC number must be a number greater than or equal to 1; '
            '"%s" is invalid.' % text, line=lineno)
        prb = inliner.problematic(rawtext, rawtext, msg)
        return [prb], [msg]
    # Base URL mainly used by inliner.rfc_reference, so this is correct:
    ref = inliner.document.settings.rfc_base_url + inliner.rfc_url % rfcnum
    if section is not None:
        ref += "#"+section
    options = normalize_role_options(options)
    node = nodes.reference(rawtext, 'RFC ' + str(rfcnum), refuri=ref,
                           **options)
    return [node], []

register_canonical_role('rfc-reference', rfc_reference_role)