域API

class sphinx.domains.Domain(env: BuildEnvironment)

域旨在成为一组用于描述相似性质对象的“对象”描述指令，以及用于创建对其引用相应角色。例如Python模块、类、函数等，模板语言的元素、Sphinx角色和指令等。

每个域在self.data中都有一个单独的存储，用于存储现有对象的信息以及如何引用它们，self.data必须是一个字典。它还必须实现几个函数，以统一的方式向Sphinx中允许用户以域无关的方式引用或搜索对象的部分公开对象信息。

关于self.data：由于所有对象和交叉引用信息都存储在BuildEnvironment实例上，因此domain.data对象也存储在env.domaindata字典中，键为domain.name。在构建过程开始之前，每个活动的域都被实例化并给定环境对象；domaindata字典必须不存在，或者是一个其“version”键等于域类的data_version属性的字典。否则，将引发OSError并丢弃pickle化的环境。

add_object_type(name: str, objtype: ObjType) → None

添加对象类型。

check_consistency() → None

执行一致性检查（实验性）。

clear_doc(docname: str) → None

删除域特定清单中文档的痕迹。

directive(name: str) → type[Directive] | None

返回一个指令适配器类，该类始终将其完整名称（“domain:name”）作为self.name注册的指令。

get_enumerable_node_type(node: Node) → str | None

获取可枚举节点的类型（实验性）。

get_full_qualified_name(node: Element) → str | None

返回给定节点的完全限定名称。

get_objects() → Iterable[tuple[str, str, str, str, str, int]]

返回“对象描述”的可迭代对象。

对象描述是包含六个项目的元组

name

完全限定名称。

dispname

搜索/链接时显示的名称。

type

对象类型，self.object_types中的一个键。

docname

要查找它的文档。

anchor

对象的锚点名称。

priority

对象的重要性（决定在搜索结果中的位置）。以下之一：

1

默认优先级（置于全文匹配之前）。

0

对象重要（置于默认优先级对象之前）。

2

对象不重要（置于全文匹配之后）。

-1

对象根本不应出现在搜索中。

get_type_name(type: ObjType, primary: bool = False) → str

返回给定ObjType的完整名称。

merge_domaindata(docnames: Set[str], otherdata: dict[str, Any]) → None

将来自不同域数据清单（来自并行构建中的子进程）的有关docnames的数据合并。

process_doc(env: BuildEnvironment, docname: str, document: nodes.document) → None

处理文档后由环境读取。

process_field_xref(pnode: pending_xref) → None

处理在文档字段中创建的待定交叉引用。例如，附加有关当前范围的信息。

resolve_any_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, target: str, node: pending_xref, contnode: Element) → list[tuple[str, nodes.reference]]

使用给定的target解析pending_xref node。

引用来自“any”或类似的role，这意味着我们不知道类型。否则，参数与resolve_xref()相同。

该方法必须返回一个元组列表（可能为空）('domain:role', newnode)，其中'domain:role'是可能创建相同引用的角色的名称，例如'py:func'。newnode是resolve_xref()将返回的值。

版本 1.3 中添加。

resolve_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, typ: str, target: str, node: pending_xref, contnode: Element) → nodes.reference | None

使用给定的typ和target解析pending_xref node。

此方法应返回一个新节点，替换xref节点，其中包含contnode，它是交叉引用的标记内容。

如果找不到解析，可以返回None；xref节点将发送到missing-reference事件，如果该事件没有产生解析，则替换为contnode。

该方法还可以引发sphinx.environment.NoUri来抑制missing-reference事件的触发。

role(name: str) → RoleFunction | None

返回一个角色适配器函数，该函数始终将其完整名称（“domain:name”）作为第一个参数赋予注册的角色。

setup() → None

设置域对象。

dangling_warnings: ClassVar[dict[str, str]] = {}

角色名称 -> 如果引用缺失则发出警告消息

data: dict[str, Any]

数据值

data_version: ClassVar[int] = 0

数据版本，当self.data的格式发生变化时，增加此值

directives: ClassVar[dict[str, type[Directive]]] = {}

指令名称 -> 指令类

enumerable_nodes: ClassVar[dict[type[Node], tuple[str, TitleGetter | None]]] = {}

node_class -> (enum_node_type, title_getter)

indices: ClassVar[list[type[Index]]] = []

索引子类列表

initial_data: ClassVar[dict[str, Any]] = {}

新环境的数据值

label: ClassVar[str] = ''

域标签：更长、更具描述性（用于消息）

name: ClassVar[str] = ''

域名：应简短但唯一

object_types: ClassVar[dict[str, ObjType]] = {}

类型（通常是指令）名称 -> ObjType 实例

roles: ClassVar[dict[str, RoleFunction | XRefRole]] = {}

角色名称 -> 可调用角色

class sphinx.domains.ObjType(lname: str, /, *roles: Any, **attrs: Any)

ObjType是对域可以记录的对象类型进行描述。在Domain子类的object_types属性中，对象类型名称映射到此类的实例。

构造函数参数

• lname：类型的本地化名称（不包括域名）

• roles：可以引用此类型对象的所有角色

• attrs：对象属性——目前只知道“searchprio”，它定义了对象在全文搜索索引中的优先级，请参阅Domain.get_objects()。

class sphinx.domains.Index(domain: Domain)

Index是对域特定索引的描述。要向域添加索引，请继承Index类，覆盖三个名称属性

• name是用于生成文件名的标识符。它还用作索引的超链接目标。因此，用户可以使用ref角色和组合域名和name属性的字符串（例如:ref:`py-modindex`）来引用索引页面。

• localname是索引的章节标题。

• shortname是索引的简称，用于HTML输出中的关系栏。可以为空以禁用关系栏中的条目。

并提供generate()方法。然后，将索引类添加到您的域的indices列表中。扩展可以使用add_index_to_domain()将索引添加到现有域。

3.0 版本发生变化: 索引页面可以通过域名和索引名称通过ref角色引用。

abstractmethod generate(docnames: Iterable[str] | None = None) → tuple[list[tuple[str, list[IndexEntry]]], bool]

获取索引的条目。

如果给定docnames，则限制为引用这些docname的条目。

返回值是(content, collapse)的元组

collapse

一个布尔值，用于确定子条目是否应折叠（对于支持折叠子条目的输出格式）。

content:

一个(letter, entries)元组序列，其中letter是给定entries的“标题”，通常是起始字母，entries是单个条目的序列。每个条目都是一个IndexEntry。

class sphinx.domains.IndexEntry(name: str, subtype: int, docname: str, anchor: str, extra: str, qualifier: str, descr: str)

索引条目。

注意

qualifier和description在某些输出格式（如LaTeX）中不渲染。

name: str

要显示的索引条目名称。

subtype: int

子条目相关类型。以下之一：

0

一个普通条目。

1

带子条目的条目。

2

一个子条目。

docname: str

条目所在的docname。

anchor: str

docname中条目的锚点

extra: str

条目的额外信息。

qualifier: str

描述的限定符。

descr: str

条目的描述。

class sphinx.directives.ObjectDescription(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

描述类、函数或类似对象的指令。

不直接使用，而是作为子类（在特定域指令中）以添加自定义行为。

_object_hierarchy_parts(sig_node: desc_signature) → tuple[str, ...]

返回一个字符串元组，每个字符串是对象层次结构的一部分（例如('module', 'submodule', 'Class', 'method')）。返回的元组用于在目录中正确嵌套父级下的子级，也可以在_toc_entry_name()方法中使用。

此方法不得在目录生成之外使用。

_toc_entry_name(sig_node: desc_signature) → str

返回对象的目录条目文本。

此函数在run()中调用一次，以设置目录条目的名称（在对象节点上设置一个特殊属性_toc_name，稍后在environment.collectors.toctree.TocTreeCollector.process_doc().build_toc()收集目录条目时使用）。

为了支持其对象的目录条目，域必须重写此方法，同时也要遵守配置设置toc_object_entries_show_parents。域还必须重写_object_hierarchy_parts()，其中包含对象层次结构每个部分的（字符串）条目。此方法的结果设置在签名节点上，并且可以作为sig_node['_toc_parts']在此方法中使用。生成的元组还用于在目录中正确嵌套父级下的子级。

此方法的一个示例实现在python域中（PyObject._toc_entry_name()）。python域在handle_signature()方法中设置_toc_parts属性。

add_target_and_index(name: ObjDescT, sig: str, signode: desc_signature) → None

如果适用，向self.indexnode添加交叉引用ID和条目。

name是handle_signature()返回的任何值。

after_content() → None

内容解析后调用。

用于重置构建环境中当前指令上下文的信息。

before_content() → None

内容解析前调用。

用于设置构建环境中当前指令上下文的信息。

get_signatures() → list[str]

从指令参数中检索要记录的签名。

默认情况下，签名作为参数给出，每行一个。

handle_signature(sig: str, signode: desc_signature) → ObjDescT

解析签名sig。

然后将各个节点附加到signode。如果引发ValueError，则中止解析，并将整个sig放入单个desc_name节点中。

返回值应该是一个标识对象的值。它会原封不动地传递给add_target_and_index()，否则仅用于跳过重复项。

run() → list[Node]

主要指令入口函数，当docutils遇到指令时调用。

这个指令的目的是非常容易被子类化，所以它委托给几个额外的方法。它的作用是：

• 找出是否作为域特定指令调用，设置 self.domain

• 创建一个desc节点以容纳所有描述

• 解析标准选项，目前是no-index

• 如果需要，创建索引节点作为 self.indexnode

• 使用 self.handle_signature() 解析所有给定的签名（由 self.get_signatures() 返回），该方法应返回一个名称或引发 ValueError

• 使用 self.add_target_and_index() 添加索引条目

• 解析内容并处理其中的文档字段

transform_content(content_node: desc_content) → None

可用于操作内容。

在通过嵌套解析创建内容之后，但在发出object-description-transform事件之前，以及在信息字段转换之前调用。

final_argument_whitespace = True

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

has_content = True

指令可以有内容吗？

option_spec: ClassVar[OptionSpec] = {'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>}

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

optional_arguments = 0

所需参数后的可选参数数量。

required_arguments = 1

所需指令参数的数量。

Python域

class sphinx.domains.python.PythonDomain(env: BuildEnvironment)

Python 语言领域。

objects

modules

note_object(name: str, objtype: str, node_id: str, aliased: bool = False, location: Any = None) → None

注意一个用于交叉引用的 Python 对象。

2.1 版本新增。

note_module(name: str, node_id: str, synopsis: str, platform: str, deprecated: bool) → None

注意一个用于交叉引用的 Python 模块。

2.1 版本新增。

上一页

Docutils 标记 API

下一页

解析器 API