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

选项和内容参数仅用于通过 role 指令创建的自定义角色.返回值是一个包含两个列表的元组,第一个包含来自角色的文本节点和元素,第二个包含生成的任何系统消息.更多信息,请参见 Docutils 的自定义角色概述.

创建自定义角色¶

Sphinx 提供了两个用于创建自定义角色的基类,:class:~sphinx.util.docutils.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.

参见

创建指令 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)
    # or
    self.state.nested_parse(self.result, 0, 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() 取代.

视图列表和字符串列表¶

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

Directive.content 属性是一个 StringList.如果你生成的内容需要被解析为 reStructuredText,你必须为 Docutils API 创建一个 StringList.Sphinx 提供的实用函数会自动处理这一点.对于内容生成,以下几点非常重要:

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