域 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

合并来自不同域数据清单的*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, Element]]

使用给定的 target 解析挂起的 xref 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

解决具有给定 typ 和 target 的待处理交叉引用 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]] = {}

directive name -> 指令类

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

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

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

Index子类列表

initial_data: dict = {}

新环境的数据值

label = ''

更长,更具描述性（用于消息）

类型:

域标签

name = ''

应该简短,但独特

类型:

域名

object_types: dict[str, ObjType] = {}

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

roles: dict[str, RoleFunction | XRefRole] = {}

role name -> 角色可调用

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 类,并重写三个名称属性:

• name is an identifier used for generating file names. It is also used for a hyperlink target for the index. Therefore, users can refer the index page using ref role and a string which is combined domain name and name attribute (ex. :ref:`py-modindex`).

• localname is the section title for the index.

• shortname is a short name for the index, for use in the relation bar in HTML output. Can be empty to disable entries in the relation bar.

并提供一个 generate() 方法.然后,将索引类添加到您领域的 indices 列表中.扩展可以使用 add_index_to_domain() 向现有领域添加索引.

在 3.0 版本发生变更: 索引页面可以通过域名和索引名通过 ref 角色进行引用.

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

获取索引的条目.

如果给定了 docnames ,则限制为引用这些 docnames 的条目.

返回值是一个元组 (content, collapse) :

collapse

一个布尔值,用于确定子条目是否应该默认折叠（适用于支持折叠子条目的输出格式）.

content:

一系列 (字母, 条目) 元组,其中 字母 是给定 条目 的 “标题”,通常是起始字母,而 条目 是单个条目的序列.每个条目是一个序列 [名称, 子类型, 文档名称, 锚点, 额外, 修饰符, 描述] .这个序列中的各个项具有以下含义:

name

要显示的索引条目名称.

subtype

与子条目相关的类型.包括:

0

一个普通条目.

1

一个带有子条目的条目.

2

一个子条目.

docname

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领域在:py:meth:handle_signature() 方法中设置 _toc_parts 属性.

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.get_signatures() 返回）,使用 self.handle_signature(),该方法应返回一个名称或引发 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

Note a python object for cross reference.

Added in version 2.1.

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

Note a python module for cross reference.

Added in version 2.1.

Previous

Docutils 标记 API

Next

解析器 API