领域API

class sphinx.domains.Domain(env: BuildEnvironment)

域是一组类似性质的对象的“对象”描述指令，以及创建对它们的引用的相应角色。例如，python模块、类、函数等、模板语言元素、sphinx角色和指令等。

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

关于 self.data ：由于所有对象和交叉引用信息都存储在BuildEnvironment实例上，因此 domain.data 对象也存储在 env.domaindata 在钥匙下听写 domain.name . 在构建过程开始之前，每个活动域都被实例化并给定环境对象；以及 domaindata dict必须不存在，或者字典的'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]]

返回“对象描述”的iterable。

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

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

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

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, Element]]

解决挂起的外部参照 node 用给定的 目标 .

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

方法必须返回元组列表（可能为空） ('domain:role', newnode) 在哪里 'domain:role' 是可以创建相同引用的角色的名称，例如 'py:func' . newnode 是什么 resolve_xref() 会回来。

Added in version 1.3.

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

解决挂起的外部参照 node 用给定的 typ 和 目标 .

此方法应返回一个新节点，以替换包含 接触器 这是交叉引用的标记内容。

如果找不到分辨率，则无法返回任何分辨率；然后将外部参照节点提供给 missing-reference 事件，如果无法解决，则替换为 接触器 .

该方法还可以提高 sphinx.environment.NoUri 压制 missing-reference 正在发出的事件。

role(name: str) → RoleFunction | None

返回一个角色适配器函数，该函数始终将注册角色的全名（“域名：名称”）作为第一个参数。

setup() → None

设置域对象。

dangling_warnings: dict[str, str] = {}

角色名称->如果缺少引用，则显示警告消息

data: dict

数据值

data_version = 0

数据版本，当格式为 self.data 变化

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

指令名->指令类

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

node_class->（enum_node_type，title_getter）

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是域可以记录的对象类型的描述。在域子类的object_types属性中，对象类型名称映射到此类的实例。

构造函数参数：

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

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

• 阿特斯 ：object attributes--当前只知道“searchprio”，它在全文搜索索引中定义对象的优先级，请参见 Domain.get_objects() .

class sphinx.domains.Index(domain: Domain)

索引是对特定于域的索引的描述。要向域添加索引，请使用子类索引，覆盖三个名称属性：

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

• localname 是索引的节标题。

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

提供一个 generate() 方法。然后，将索引类添加到域的 indices 名单。扩展可以使用向现有域添加索引 add_index_to_domain() .

在 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 是单个条目的序列。每个条目都是一个序列 [name, subtype, docname, anchor, extra, qualifier, descr] . 此序列中的项目具有以下含义：

name

要显示的索引项的名称。

subtype

与子条目相关的类型。什么之中的一个：

0

一个正常的入口。

1

带有子条目的条目。

2

子条目。

docname

文档名称 入口所在位置。

anchor

内的入口锚定 docname

extra

条目的额外信息。

qualifier

描述的限定符。

descr

条目的说明。

某些输出格式（如LaTex）不提供限定符和说明。

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域将设置 _toc_parts 属性中的 handle_signature() 方法。

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

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

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(contentnode: 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对象。

Added in version 2.1.

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

请注意用于交叉引用的python模块。

Added in version 2.1.