域名API¶
- class sphinx.domains.Domain(env: BuildEnvironment)[源代码]¶
域是一组类似性质的对象的“对象”描述指令，以及创建对它们的引用的相应角色。例如，Python模块、类、函数等、模板语言的元素、Sphinx角色和指令等。
每个域都有单独的存储空间，用于存储有关现有对象以及如何在中引用它们的信息 self.data ，它必须是一本词典。它还必须实现几个函数，以统一的方式将对象信息公开给允许用户以与域无关的方式引用或搜索对象的Sphinx部分。
关于 self.data ：由于所有对象和交叉引用信息都存储在BuildEnvironment实例上，因此 domain.data 对象也存储在 env.domaindata 关键字下的DICT domain.name 。在构建过程开始之前，每个活动域都被实例化并被赋予环境对象； domaindata 则DICT必须是不存在的，或者是其‘VERSION’关键字等于域类‘
data_version属性。否则， OSError 将引发，并丢弃已酸洗的环境。- get_objects() Iterable[tuple[str, str, str, str, str, int]][源代码]¶
返回一个可迭代的“对象描述”。
对象描述是包含六个项的元组：
name完全限定名称。
dispname搜索/链接时要显示的名称。
type对象类型，关键字
self.object_types。docname要找到它的文档。
anchor对象的锚点名称。
priority对象有多“重要”(决定在搜索结果中的位置)。以下选项之一：
1默认优先级(放在全文匹配之前)。
0对象很重要(放在默认优先级对象之前)。
2对象不重要(放置在全文匹配之后)。
-1对象根本不应该出现在搜索中。
- 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]][源代码]¶
解析挂起的外部参照_xref node 与给定的 target 。
引用来自“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) nodes.reference | None[源代码]¶
解析挂起的外部参照_xref node 与给定的 typ 和 target 。
此方法应返回一个新节点，以替换外部参照节点，该节点包含 contnode 这是交叉引用的标记内容。
如果找不到分辨率，则不能返回任何分辨率；然后将外部参照节点提供给
missing-reference事件，如果这不产生任何解决方案，则替换为 contnode 。该方法还可以提高
sphinx.environment.NoUri要抑制missing-reference正在发出的事件。
- data_version = 0¶
数据版本，当格式发生变化时，会出现这种情况 self.data 变化
- label = ''¶
域标签：更长、更具描述性(用于消息)
- name = ''¶
域名：应简短，但必须唯一
- class sphinx.domains.ObjType(lname: str, /, *roles: Any, **attrs: Any)[源代码]¶
ObjType是对域可以记录的对象类型的描述。在域子类的OBJECT_TYPE属性中，对象类型名称映射到此类的实例。
构造函数参数：
lname ：类型的本地化名称(不包括域名)
roles ：可以引用此类型对象的所有角色
attrs ：对象属性--目前只知道定义对象在全文搜索索引中的优先级的“searchprio”，请参见
Domain.get_objects()。
- class sphinx.domains.Index(domain: Domain)[源代码]¶
索引是对特定于域的索引的描述。要向域添加索引，子类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，则仅限于引用这些文档名称的条目。返回值是
(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。
- 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()回来了。
- handle_signature(sig: str, signode: desc_signature) ObjDescT[源代码]¶
解析签名 sig .
然后将各个节点附加到 signode .如果引发ValueRight，解析将中止，整个 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¶
所需的指令参数数。