域 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 化的环境。- directive(name: str) type[Directive] | None [源代码]¶
返回一个指令适配器类,该类始终将注册指令的全名(‘domain:name’)作为
self.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 [源代码]¶
合并来自不同 domaindata 清单的关于 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” 或类似角色,这意味着我们不知道类型。否则,参数与
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
事件。
- data_version = 0¶
数据版本,当 self.data 的格式更改时,增加此版本号
- enumerable_nodes: dict[type[Node], tuple[str, TitleGetter | None]] = {}¶
node_class -> (enum_node_type, title_getter)
- label = ''¶
域标签:更长,更具描述性(用于消息)
- name = ''¶
域名:应该简短,但唯一
- class sphinx.domains.ObjType(lname: str, /, *roles: Any, **attrs: Any)[source]¶
ObjType 是对域可以文档化的对象类型的描述。在 Domain 子类的 object_types 属性中,对象类型名称被映射到此类的实例。
构造函数参数
lname: 类型的本地化名称(不包含域名)
roles: 可以引用此类型对象的所有角色
attrs: 对象属性 – 目前只知道 “searchprio”,它定义了对象在全文搜索索引中的优先级,请参阅
Domain.get_objects()
。
- class sphinx.domains.Index(domain: Domain)[source]¶
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] [source]¶
获取索引的条目。
如果给定
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)[source]¶
索引条目。
注解
qualifier 和 description 不会为某些输出格式呈现,例如 LaTeX。
- class sphinx.directives.ObjectDescription(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶
用于描述类、函数或类似对象的指令。
不直接使用,而是被子类化(在特定于域的指令中)以添加自定义行为。
- _object_hierarchy_parts(sig_node: desc_signature) tuple[str, ...] [source]¶
返回字符串元组,对象的层次结构的每个部分对应一个条目 (例如
('module', 'submodule', 'Class', 'method')
)。返回的元组用于在目录中正确地将子项嵌套在父项中,并且也可以在_toc_entry_name()
方法中使用。此方法不得在目录生成之外使用。
- _toc_entry_name(sig_node: desc_signature) str [source]¶
返回对象的目录条目的文本。
此函数在
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 [source]¶
如果适用,则向 self.indexnode 添加交叉引用 ID 和条目。
name 是
handle_signature()
返回的任何内容。
- handle_signature(sig: str, signode: desc_signature) ObjDescT [source]¶
解析签名 sig。
然后将各个节点附加到 signode。如果引发 ValueError,则解析中止,并将整个 sig 放入单个 desc_name 节点中。
返回值应该是一个标识对象的值。它被传递到
add_target_and_index()
,并且仅用于跳过重复项。
- run() list[Node] [source]¶
主指令入口函数,在 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 [source]¶
可用于操作内容。
在通过嵌套解析创建内容之后,但在发出
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¶
必需的指令参数的数量。