Sphinx

# Docutils markup API

This section describes the API for adding reStructuredText markup elements (roles and directives).

## Roles

Roles follow the interface described below. They have to be registered by an extension using `Sphinx.add_role()` or `Sphinx.add_role_to_domain()`.

    def role_function(
        role_name: str, raw_source: str, text: str,
        lineno: int, inliner: Inliner,
        options: dict = {}, content: list = [],
    ) -> tuple[list[Node], list[system_message]]:
        elements = []
        messages = []
        return elements, messages

The options and content parameters are only used for custom roles created via the role directive. The return value is a tuple of two lists, the first containing the text nodes and elements from the role, and the second containing any system messages generated. For more information, see the custom role overview from Docutils.

### Creating custom roles

Sphinx provides two base classes for creating custom roles, `SphinxRole` and `ReferenceRole`.

These provide a class-based interface for creating roles, where the main logic must be implemented in your `run()` method. The classes provide a number of useful methods and attributes, such as `self.text`, `self.config`, and `self.env`. The `ReferenceRole` class implements Sphinx’s `title <target>` logic, exposing `self.target` and `self.title` attributes. This is useful for creating cross-reference roles.

## Directives

Directives are handled by classes derived from `docutils.parsers.rst.Directive`. They have to be registered by an extension using `Sphinx.add_directive()` or `Sphinx.add_directive_to_domain()`.

class docutils.parsers.rst.Directive

  The markup syntax of the new directive is determined by the follow five class attributes:

  required_arguments = 0

    Number of required directive arguments.

  optional_arguments = 0

    Number of optional arguments after the required arguments.

  final_argument_whitespace = False

    May the final argument contain whitespace?

  option_spec = None

    Mapping of option names to validator functions.

    Option validator functions take a single parameter, the option argument (or `None` if not given), and should validate it or convert it to the proper form. They raise `ValueError` or `TypeError` to indicate failure.

    There are several predefined and possibly useful validators in the `docutils.parsers.rst.directives` module.

  has_content = False

    May the directive have content?

  New directives must implement the `run()` method:

  run()

    This method must process the directive arguments, options and content, and return a list of Docutils/Sphinx nodes that will be inserted into the document tree at the point where the directive was encountered.

  Instance attributes that are always set on the directive are:

  name

    The directive name (useful when registering the same directive class under multiple names).

  arguments

    The arguments given to the directive, as a list.

  options

    The options given to the directive, as a dictionary mapping option names to validated/converted values.

  content

    The directive content, if given, as a `ViewList`.

  lineno

    The absolute line number on which the directive appeared. This is not always a useful value; use `srcline` instead.

  content_offset

    Internal offset of the directive content. Used when calling `nested_parse` (see below).

  block_text

    The string containing the entire directive.

  state
  state_machine

    The state and state machine which controls the parsing. Used for `nested_parse`.

See also

Creating directives HOWTO of the Docutils documentation

### Parsing directive content as reStructuredText

Many directives will contain more markup that must be parsed. To do this, use one of the following APIs from the `run()` method:

- `SphinxDirective.parse_content_to_nodes()`

- `SphinxDirective.parse_text_to_nodes()`

The first method parses all the directive’s content as markup, whilst the second only parses the given text string. Both methods return the parsed Docutils nodes in a list.

The methods are used as follows:

    def run(self) -> list[Node]:
        # either
        parsed = self.parse_content_to_nodes()
        # or
        parsed = self.parse_text_to_nodes('spam spam spam')
        return parsed

Note

The above utility methods were added in Sphinx 7.4. Prior to Sphinx 7.4, the following methods should be used to parse content:

- `self.state.nested_parse`

- `sphinx.util.nodes.nested_parse_with_titles()` – this allows titles in the parsed content.

    def run(self) -> list[Node]:
        container = docutils.nodes.Element()
        # either
        nested_parse_with_titles(self.state, self.result, container)
        # or
        self.state.nested_parse(self.result, 0, container)
        parsed = container.children
        return parsed

To parse inline markup, use `parse_inline()`. This must only be used for text which is a single line or paragraph, and does not contain any structural elements (headings, transitions, directives, etc).

Note

`sphinx.util.docutils.switch_source_input()` allows changing the source (input) file during parsing content in a directive. It is useful to parse mixed content, such as in `sphinx.ext.autodoc`, where it is used to parse docstrings.

    from sphinx.util.docutils import switch_source_input
    from sphinx.util.parsing import nested_parse_to_nodes

    # Switch source_input between parsing content.
    # Inside this context, all parsing errors and warnings are reported as
    # happened in new source_input (in this case, ``self.result``).
    with switch_source_input(self.state, self.result):
        parsed = nested_parse_to_nodes(self.state, self.result)

Deprecated since version 1.7: Until Sphinx 1.6, `sphinx.ext.autodoc.AutodocReporter` was used for this purpose. It is replaced by `switch_source_input()`.

### ViewLists and StringLists

Docutils represents document source lines in a `StringList` class, which inherits from `ViewList`, both in the `docutils.statemachine` module. This is a list with extended functionality, including that slicing creates views of the original list and that the list contains information about source line numbers.

The `Directive.content` attribute is a `StringList`. If you generate content to be parsed as reStructuredText, you have to create a `StringList` for the Docutils APIs. The utility functions provided by Sphinx handle this automatically. Important for content generation are the following points:

- The `ViewList` constructor takes a list of strings (lines) and a source (document) name.

- The `ViewList.append()` method takes a line and a source name as well.