域接口

class sphinx.domains.Domain(env: BuildEnvironment)

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

每个域都有一个单独的存储区，用于存储有关现有对象以及如何在中引用它们的信息`自我数据`，一定是字典。它还必须实现几个函数，以统一的方式向Sphinx的部分公开对象信息，从而允许用户以不确定域的方式引用或搜索对象。

关于`自我数据`：由于所有对象和交叉引用信息都存储在BuildEnvironment实例上，因此`域.data`对象也存储在`环境域数据`钥匙下的dict`域名`. 在生成过程开始之前，每个活动域都被实例化并给定环境对象；“domaindata”必须是不存在的，或者是“version”键等于domain类的字典：attr:`data_version`属性。否则，将引发“OSError”，并丢弃处理环境。

add_object_type(name: str, objtype: ObjType) → None

添加对象类型。

check_consistency() → None

进行一致性检查（实验性）。

clear_doc(docname: str) → None

删除域特定清单中文档的痕迹。

directive(name: str) → Callable | None

返回一个指令适配器类，该类始终为已注册的指令提供其全名（’域名：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]]

返回一个迭代器的“对象描述”。

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

名字

完全限定名。

显示名称

搜索/链接时要显示的名称。

类型

对象类型，一个键``self.object_类型``.

文档名

找到它的文件。

定位点

对象的定位点名称。

优先权

对象的“重要性”（决定搜索结果中的位置）。之一：

1

默认优先级（放在全文匹配项之前）。

0

对象很重要（放在默认优先级对象之前）。

2

对象不重要（放在全文匹配之后）。

-1

对象不应在搜索中显示。

get_type_name(type: ObjType, primary: bool = False) → str

返回给定对象类型的全名。

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

使用给定的*目标*解析挂起的u xref*节点*。

引用来自“any”或类似的角色，这意味着我们不知道类型。否则，参数与for:meth:`resolve_xref`相同。

该方法必须返回元组的列表（可能为空）(‘domain:role’, newnode）``，其中``域：角色’是可能创建相同引用的角色的名称，例如'`'py:func'`。``newnode``返回的是：meth:`resolvexref`将返回的内容。

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*解析挂起的u xref*节点*。

此方法应返回一个新节点，以替换外部参照节点，该节点包含交叉引用的标记内容*contnode*。

如果找不到解析，则无法返回任何解析；然后将xref节点提供给：event:`missing reference`事件，如果该事件没有生成解析，则用*contnode*替换。

该方法还可以引发：exc:`sphinx.environment.NoUri：event:正在发出的“missing reference”事件。

role(name: str) → RoleFunction | None

返回一个角色适配器函数，该函数始终为注册的角色提供其全名（’域名：name’作为第一个参数。

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]] = {}

节点类型->（枚举节点类型，标题获取）

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

索引子类的列表

initial_data: dict = {}

全新环境的数据值

label = ''

域标签：更长，更具描述性（用于邮件中）

name = ''

域名：应简短，但唯一

object_types: dict[str, ObjType] = {}

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

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

角色名称->角色可调用

class sphinx.domains.ObjType(lname: str, *roles: Any, **attrs: Any)

对象类型是域可以记录的对象类型的描述。在域子类的object_types属性中，对象类型名映射到该类的实例。

构造函数参数：

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

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

• attrs：object attributes——目前只知道“searchprio”，它定义了全文搜索索引中对象的优先级，请参见：meth:Domain.get_对象().

class sphinx.domains.Index(domain: Domain)

索引是特定于域的索引的描述。要向域添加索引，请使用子类index，重写三个name属性：

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

• “localname”是索引的节标题。

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

并提供一个：meth:generate（）`方法。然后，将index类添加到域的“index”列表中。扩展可以使用以下方法向现有域添加索引：`~sphinx.application.sphinx。将“u index”添加到“u domain（）”。

在 3.0 版本发生变更: 索引页可以通过以下方式按域名和索引名引用：rst:角色：`ref`角色。

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

获取索引项。

如果给定了“docnames”，则限制为引用这些文档名的条目。

返回值是一个元组``（content，collapse）``：

collapse

一个布尔值，用于确定子条目是否应开始折叠（对于支持折叠子条目的输出格式）。

content:

一个`（字母，条目）``元组的序列，其中``字母``是给定``条目``的“标题”，通常是起始字母，entries`是单个词条的序列。每个条目都是一个序列`[name，subtype，docname，anchor，extra，qualifier，descr]。此序列中的项目具有以下含义：

名字

要显示的索引项的名称。

subtype

子条目相关类型。之一：

0

正常的条目。

1

包含子条目的条目。

2

子条目。

文档名

条目所在的*文档名*。

定位点

在``docname``中定位项

extra

条目的附加信息。

qualifier

描述的限定符。

descr

条目的说明。

对于某些输出格式（如LaTeX），不呈现限定符和描述。

class sphinx.directives.ObjectDescription(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Directive to describe a class, function or similar object. Not used directly, but subclassed (in domain-specific directives) to add custom behavior.

_object_hierarchy_parts(sig_node: desc_signature) → tuple[str, ...]

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

_toc_entry_name(sig_node: desc_signature) → str

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

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

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

after_content() → None

Called after parsing content. Used to reset information about the current directive context on the build environment.

before_content() → None

Called before parsing content. Used to set information about the current directive context on the build environment.

get_signatures() → list[str]

Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.

handle_signature(sig: str, signode: desc_signature) → ObjDescT

Parse the signature sig into individual nodes and append them to signode. If ValueError is raised, parsing is aborted and the whole sig is put into a single desc_name node.

The return value should be a value that identifies the object. It is passed to add_target_and_index() unchanged, and otherwise only used to skip duplicates.

run() → list[Node]

Main directive entry function, called by docutils upon encountering the directive.

This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:

• find out if called as a domain-specific directive, set self.domain

• create a desc node to fit all description inside

• parse standard options, currently no-index

• create an index node if needed as self.indexnode

• parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError

• add index entries using self.add_target_and_index()

• parse the content and handle doc fields in it

transform_content(contentnode: desc_content) → None

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.

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.