域 API

class sphinx.domains.Domain(env: BuildEnvironment)

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

每个域都具有独立的存储空间，用于存储有关现有对象的信息以及如何在 self.data 中引用它们，该存储空间必须是字典。它还必须实现几个函数，以统一的方式公开对象信息，以便 Sphinx 的各部分能够以与域无关的方式引用或搜索对象。

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

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

添加对象类型。

check_consistency() → None

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

clear_doc(docname: str) → None

从域特定的库存中删除文档的痕迹。

directive(name: str) → Callable | 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: list[str], otherdata: dict[str, Any]) → None

将来自不同 domaindata 库存（来自并行构建中的子进程）的有关 docnames 的数据合并。

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

在环境读取文档后处理该文档。

process_field_xref(pnode: pending_xref) → None

处理在文档字段中创建的挂起 xref。例如，附加有关当前范围的信息。

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

使用给定的 target 解析 pending_xref node。

引用来自“any”或类似角色，这意味着我们不知道类型。否则，参数与 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) → Element | 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: dict[str, str] = {}

角色名称 -> 如果引用丢失，则为警告消息

data: dict[str, Any]

数据值

data_version = 0

数据版本，当 self.data 的格式更改时，请增加此值

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

指令名称 -> 指令类

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

节点类 -> (枚举节点类型，标题获取器)

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

索引子类的列表

initial_data: dict = {}

全新环境的数据值

label = ''

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

name = ''

域名称：应简短，但唯一

object_types: dict[str, ObjType] = {}

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

roles: 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() 将索引添加到现有域。

Changed in version 3.0: 索引页面可以通过域名称和索引名称通过 ref 角色来引用。

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

获取索引条目。

如果提供了 docnames，则限制为引用这些文档名称的条目。

返回值是一个元组 (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)

索引条目。

注意

对于某些输出格式（例如 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[dict[str, Callable[[str], Any]]] = {'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 版本中添加。

Previous

Docutils 标记 API

Next

解析器 API