Docutils标记接口

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

角色

指令

指令由派生自``docutils.parsers.rst。指令``。它们必须通过使用：meth:的扩展进行注册。Sphinx.add_指令`或者：冰毒。Sphinx.add_指令_到u域.

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

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

required_arguments = 0

必需的指令参数数。

optional_arguments = 0

必需参数后的可选参数数目。

final_argument_whitespace = False

最后一个参数可以包含空格吗？

option_spec = None

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

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

在：mod:mod:`docutils.parsers.rst.directives`模块。

has_content = False

指令是否有内容？

新指令必须实现：meth:`run`方法：

run()[源代码]

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

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

name

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

arguments

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

options

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

content

The directive content, if given, as a ViewList.

lineno

出现指令的绝对行号。这并不总是有用的值；请改用：attr:`srcline’。

content_offset

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

block_text

包含整个指令的字符串。

state
state_machine

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

查看列表

Docutils表示类中的文档源行``docutils.statemachine.ViewList``. 这是一个具有扩展功能的列表——首先，切片创建原始列表的视图，并且该列表还包含有关源行号的信息。

属性：`Directive.content`属性是一个ViewList。如果生成要解析为ReST的内容，则必须自己创建一个ViewList。以下几点对于内容生成很重要：

  • 构造函数接受字符串（行）和源（文档）名称的列表。

  • `.append（）``方法也接受一行和一个源名称。

将指令内容解析为ReST

许多指令将包含更多必须解析的标记。为此，请使用以下API中的一个：meth：`指令.运行`方法：

  • self.state.nested_parse

  • ：函数：sphinx.util.nodes.nested_parse_with_titles—这允许解析内容中包含标题。

这两个接口都将内容解析为给定的节点。它们是这样使用的：

node = docutils.nodes.paragraph()
# either
nested_parse_with_titles(self.state, self.result, node)
# or
self.state.nested_parse(self.result, 0, node)

备注

``sphinx.util.docutils.switch_source_input()```允许在嵌套分析期间更改目标文件。它对混合内容很有用。例如，斯芬克斯。外部自动文档``用于分析文档字符串:：

from sphinx.util.docutils import switch_source_input

# 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):
    node = docutils.nodes.paragraph()
    self.state.nested_parse(self.result, 0, node)

自 1.7 版本弃用: Until Sphinx 1.6, sphinx.ext.autodoc.AutodocReporter was used for this purpose. It is replaced by switch_source_input().

如果不需要包装节点，可以使用任何具体的节点类型并返回``节点.子项``从指令中。

参见

`创建Docutils文档的“HOWTO”指令