域接口¶
- class sphinx.domains.Domain(env: BuildEnvironment)[源代码]¶
域是指一组性质相似的对象的“对象”描述指令，以及创建对它们的引用的相应角色。例如Python模块、类、函数等、模板语言的元素、Sphinx角色和指令等。
每个域都有一个单独的存储区，用于存储有关现有对象以及如何在中引用它们的信息 self.data，一定是字典。它还必须实现几个函数，以统一的方式向Sphinx的部分公开对象信息，从而允许用户以不确定域的方式引用或搜索对象。
关于 self.data：由于所有对象和交叉引用信息都存储在BuildEnvironment实例上，因此 domain.data 对象也存储在 env.domaindata 字典的 domain.name 键下。在生成过程开始之前，每个活动域都被实例化并给定环境对象；domaindata 必须是不存在的，或者是 version 键等于domain类的字典
data_version属性。否则，将引发 OSError，并丢弃处理环境。- directive(name: str) type[Directive] | None[源代码]¶
返回一个指令适配器类，该类始终为已注册的指令提供其全名（'domain:name'）作为
自身名称.
- get_objects() Iterable[tuple[str, str, str, str, str, int]][源代码]¶
返回一个迭代器的“对象描述”。
对象描述是包含六项的元组：
名字完全限定名。
显示名称搜索/链接时要显示的名称。
类型对象类型，
self.object_types中的一个键。文档名找到它的文件。
定位点对象的定位点名称。
优先权对象的“重要性”（决定搜索结果中的位置）。之一：
1默认优先级（放在全文匹配项之前）。
0对象很重要（放在默认优先级对象之前）。
2对象不重要（放在全文匹配之后）。
-1对象不应在搜索中显示。
- merge_domaindata(docnames: Set[str], otherdata: dict[str, Any]) None[源代码]¶
从不同的域数据目录（来自并行构建中的子进程）合并有关 donames 的数据。
- 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”或类似的角色，这意味着我们不知道类型。否则，参数与
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 节点。
此方法应返回一个新节点，以替换外部参照节点，该节点包含交叉引用的标记内容 contnode。
如果找不到解析，则无法返回任何解析；然后将xref节点提供给
missing-reference事件，如果该事件没有生成解析，则用 contnode 替换。该方法还可以引发
sphinx.environment.NoUri防止missing-reference发出。
- class sphinx.domains.ObjType(lname: str, /, *roles: Any, **attrs: Any)[源代码]¶
对象类型是域可以记录的对象类型的描述。在域子类的object_types属性中，对象类型名映射到该类的实例。
构造函数参数：
lname：类型的本地化名称（不包括域名）
roles：可以引用此类型对象的所有角色
attrs：object attributes —— 目前只知道 "searchprio"，它定义了全文搜索索引中对象的优先级，请参见
Domain.get_objects()函数。
- class sphinx.domains.Index(domain: Domain)[源代码]¶
索引是特定于域的索引的描述。要向域添加索引，请使用子类index，重写三个name属性：
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，则限制为引用这些文档名的条目。返回值是一个元组
(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）不会呈现 qualifier 和 description。
- 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[源代码]¶
添加交叉引用ID和条目到self.indexnode（如果适用）。
name 是
handle_signature()返回的任何内容。
- 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¶
必需的指令参数数。