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 指令。返回值是由两个列表组成的二元组，第一个列表包含角色的文本节点和元素，第二个列表包含生成的任何系统消息。更多详见 custom role overview 来自Docutils。

创建自定义角色¶

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

这些提供了一个基于类的界面来创建角色，其中主要逻辑必须在 run() 法这些类提供了许多有用的方法和属性，例如 self.text , self.config ，而且 self.env .的 ReferenceRole 类实现Sphinx的 title <target> 逻辑，暴露 self.target 和 self.title 美德.先知-愿这对于创建交叉引用角色很有用。

指令¶

指令由派生自 docutils.parsers.rst.Directive 。它们必须使用扩展名进行注册 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¶

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

选项验证器函数接受单个参数，即选项参数(或 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¶: 控制分析的状态和状态机。用于 nested_parse 。

参见

Creating directives Docutils文档指南

将指令内容解析为reStructuredtext¶

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

第一种方法将所有指令的内容解析为标记，而第二种方法仅解析给定的 text string.这两个方法都会返回列表中解析的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 版本弃用: 在Sphinx1.6之前， sphinx.ext.autodoc.AutodocReporter 就是为了这个目的。它被替换为 switch_source_input() 。

视图列表和字符串列表¶

Docutils表示中的文档源行 StringList 类，它继承自 ViewList ，都在 docutils.statemachine module.这是一个具有扩展功能的列表，包括切片创建原始列表的视图，以及列表包含有关源代码行号的信息。

的 Directive.content 属性是 StringList .如果生成要解析为reStructuredtext的内容，则必须创建 StringList 用于Docutils API。Sphinx提供的实用程序函数会自动处理此问题。对于内容生成来说重要的是以下几点：

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