Docutils标记 API¶

本节介绍用于添加reStructuredText标记元素（角色和指令）的 API。

角色¶

角色遵循下面描述的接口。它们必须通过使用 Sphinx.add_role() 或 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 的 custom role overview。

创建自定义角色¶

Sphinx 提供了两个用于创建自定义角色的基类，SphinxRole 和 ReferenceRole。

这些为创建角色提供了基于类的接口，其中主要逻辑必须在您的 run() 方法中实现。这些类提供了许多有用的方法和属性，例如 self.text、self.config 和 self.env。ReferenceRole 类实现了 Sphinx 的 title <target> 逻辑，公开了 self.target 和 self.title 属性。这对于创建交叉引用角色非常有用。

指令¶

指令由派生自 docutils.parsers.rst.Directieve。它们必须通过使用 Sphinx.add_directive() 或者 Sphinx.add_directive_to_domain()

class docutils.parsers.rst.Directive[源代码]¶

新指令的标记语法由以下五个类属性确定：

required_arguments = 0¶: 必需的指令参数数。

optional_arguments = 0¶: 必需参数后的可选参数数目。

final_argument_whitespace = False¶: 最后一个参数可以包含空格吗？

option_spec = None¶

选项名到验证器函数的映射。

选项验证器函数接受一个参数，即Option参数（如果未给定，则为“None”），并应验证它或将其转换为正确的形式。它们发出 ValueError 或 TypeError 来表示失败。

docutils.parsers.rst.directives 模块里有一些预先定义的验证器。

has_content = False¶: 指令是否有内容？

新指令必须实现 run() 方法：

run()[源代码]¶: 此方法必须处理指令参数、选项和内容，并返回Docutils/Sphinx节点列表，这些节点将在遇到指令的位置插入到文档树中。

始终在指令上设置的实例属性包括：

name¶: 指令名（在多个名称下注册同一个指令类时很有用）。

arguments¶: 以列表形式提供给指令的参数。

options¶: 给指令的选项，作为将选项名称映射到已验证/转换的值的字典。

content¶: 指令内容（如果给出），作为 ViewList。

lineno¶: 出现指令的绝对行号。这并不总是有用的值；请改用 srcline。

content_offset¶: 指令内容的内部偏移量。调用“nested_parse”时使用（请参见下文）。

block_text¶: 包含整个指令的字符串。

state¶
state_machine¶: 控制解析的状态和状态机。用于“嵌套”分析。

参见

Creating directives Docutils文档的“HOWTO”

将指令内容解析为 reStructuredText¶

许多指令将包含必须解析的更多标记。为此，请在 run() 方法中使用以下 API 之一：

第一个方法将指令的所有内容解析为标记，而第二个方法仅解析给定的 text 字符串。这两种方法都以列表形式返回解析后的 Docutils 节点。

这些方法的使用方式如下：

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

备注

上述实用方法是在 Sphinx 7.4 中添加的。在 Sphinx 7.4 之前，应使用以下方法来解析内容：

self.state.nested_parse
sphinx.util.nodes.nested_parse_with_titles() -- 这允许解析内容中包含标题。

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

要解析内联标记，请使用 parse_inline()。这只能用于单行或段落的文本，并且不包含任何结构元素（标题、过渡、指令等）。

备注

sphinx.util.docutils.switch_source_input() 允许在指令中解析内容时更改源（输入）文件。它对于解析混合内容非常有用，例如在 sphinx.ext.autodoc 中，它用于解析文档字符串。

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 版本弃用: 直到 Sphinx 1.6，sphinx.ext.autodoc.AutodocReporter 才用于此目的。它被 switch_source_input() 所取代。

ViewLists 和 StringLists¶

Docutils 在 docutils.statemachine 模块中使用 StringList 类表示文档源行，该类继承自 ViewList。这是一个具有扩展功能的列表，包括切片创建原始列表的视图，并且该列表包含有关源行号的信息。

Directive.content 属性是一个 StringList。如果您生成的内容要作为 reStructuredText 进行解析，则必须为 Docutils API 创建一个 StringList。Sphinx 提供的实用程序函数会自动处理此问题。内容生成的重要点如下：

ViewList 构造函数接受字符串列表（行）和源（文档）名称。
ViewList.append() 方法也接受一行和一个源名称。