Docutils标记API

本节介绍用于添加ReST标记元素(角色和指令)的API.

角色

指令

指令由派生自 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_pa​​rse 时使用(见下文).

block_text

包含整个指令的字符串.

state
state_machine

控制解析的状态和状态机.用于 nested_pa​​rse.

查看列表

Docutils在类 docutils.statemachine.ViewList 中表示文档源代码行. 这是一个具有扩展功能的列表 - 例如, 切片创建原始列表的视图, 并且列表还包含有关源行号的信息.

Directive.content 属性是一个ViewList. 如果生成要解析为ReST的内容, 则必须自己创建ViewList. 内容生成的重要性有以下几点:

  • 构造函数获取字符串(行)和源(文档)名称的列表.

  • .append() 方法也接受一行和一个源名称.

将指令内容解析为ReST

许多指令将包含必须解析的更多标记. 为此, 请使用以下API中的一个 Directive.run() 方法:

  • self.state.nested_parse

  • sphinx.util.nodes.nested_pa​​rse_with_titles() - 这允许解析内容中的标题.

两个API都将内容解析为给定节点.它们像这样使用:

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() 允许在nested_pa​​rse期间更改目标文件.混合内容很有用.例如, sphinx.  ext.autodoc 使用它来解析docstrings

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 版后已移除: 在Sphinx-1.6之前, sphinx.ext.autodoc.AutodocReporter 用于此目的.现在, 它被 switch_source_input() 取代.

如果您不需要包装节点, 则可以使用任何具体的节点类型并从指令返回 node.children.

参见

创建指令

关于Docutils文档的HOWTO