Docutils markup API¶

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

角色¶

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

options 與 content 參數僅用於透過 role 指示詞建立的自訂角色。傳回值是一個包含兩個列表的值組，第一個列表包含來自該角色的文字節點與元素，第二個列表則包含任何生成的系統訊息。更多資訊請參見 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 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.

另請參見

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:

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

備註

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, self.content_offset)
    # or
    self.state.nested_parse(self.result, self.content_offset, 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).

備註

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)

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