域API

class sphinx.domains.Domain(env)

域意味着是一组具有类似性质的对象的“对象”描述指令, 以及用于创建对它们的引用的相应角色。 示例包括Python模块, 类, 函数等, 模板语言的元素, Sphinx角色和指令等。

每个域都有一个单独的存储空间, 用于存储有关现有对象的信息, 以及如何在 self.data 中引用它们, 它必须是字典。 它还必须实现几个函数, 这些函数以统一的方式将对象信息暴露给Sphinx的部分, 允许用户以域无关的方式引用或搜索对象。

关于`self.data`:由于所有对象和交叉引用信息都存储在BuildEnvironment实例中, domain.data 对象也存储在 domain.name 键下的`env.domaindata` 字典中。 在构建过程开始之前, 每个活动域都被实例化并被赋予环境对象;那么 domaindata 字典必须是不存在的, 或者是 ‘version’ 键等于域类 attr:data_version 属性的字典。否则, 引发 OSError 并丢弃pickle环境。

add_object_type(name, objtype)

添加对象类型。

check_consistency()

进行一致性检查(实验)。

clear_doc(docname)

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

directive(name)

返回一个指令适配器类, 它始终将注册指令的全名(‘domain:name’)作为 self.name.

get_enumerable_node_type(node)

获取可枚举节点的类型(实验性)。

get_full_qualified_name(node)

返回给定节点的完全限定名称。

get_objects()

Return an iterable of “object descriptions”.

Object descriptions are tuples with six items:

name

Fully qualified name.

dispname

Name to display when searching/linking.

type

Object type, a key in self.object_types.

docname

The document where it is to be found.

anchor

The anchor name for the object.

priority

How “important” the object is (determines placement in search results). One of:

1

Default priority (placed before full-text matches).

0

Object is important (placed before default-priority objects).

2

Object is unimportant (placed after full-text matches).

-1

Object should not show up in search at all.

get_type_name(type, primary=False)

返回给定 ObjType 的全名。

merge_domaindata(docnames, otherdata)

合并来自不同 domaindata 库存的 docnames 数据(来自并行构建中的子流程)。

process_doc(env, docname, document)

在环境读取文档后处理文档。

process_field_xref(pnode)

处理在doc字段中创建的待处理外部参照。例如, 附加有关当前范围的信息。

resolve_any_xref(env, fromdocname, builder, target, node, contnode)

使用给定的 target 解析 pending_xref node.

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

该方法必须返回一个列表(可能为空)的元组 ('domain:role', newnode), 其中 'domain:role' 是一个可以创建相同引用的角色的名称, 例如 'py:func'. newnode 是什么 resolve_xref() 会返回。

1.3 新版功能.

resolve_xref(env, fromdocname, builder, typ, target, node, contnode)

使用给定的* type 和 target 解析挂起的外部参照*节点。

此方法应返回一个新节点, 以替换xref节点, 其中包含 contnode , 它是交叉引用的标记内容。

如果找不到解决方案, 则无法返回;然后, 外部参照节点将被赋予:event:`missing-reference`事件, 如果没有产生分辨率, 则替换为 contnode.

该方法还可以引发 sphinx.environment.NoUri 来抑制 missing-reference 事件被发出。

role(name)

返回角色适配器函数, 该函数始终为注册角色提供其全名(‘domain:name’)作为第一个参数。

dangling_warnings = {}

角色名称 - >如果缺少引用, 则显示警告消息

data = None

data value

data_version = 0

数据版本, 当 self.data 的格式发生变化时, 请对此进行修改

directives = {}

指令名称 - >指令类

enumerable_nodes = {}

node_class -> (enum_node_type, title_getter)

indices = []

索引子类列表

initial_data = {}

新环境的数据价值

label = ''

域名标签:更长, 更具描述性(用于邮件)

name = ''

域名:应该简短, 但要独一无二

object_types = {}

type(通常是指令) name -> ObjType 实例

roles = {}

角色名称 -> 角色可调用

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

ObjType是域可以记录的对象类型的描述。在Domain子类的 object_types 属性中, 对象类型名称映射到此类的实例。

构造函数参数:

• lname: 类型的本地化名称(不包括域名)

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

• attrs: 对象属性 - 目前只有“searchprio ”是已知的, 它定义了全文搜索索引中对象的优先级, 参见 Domain.get_objects().

class sphinx.domains.Index(domain)

索引是特定于域的索引的描述。要向域添加索引, 请将索引子类化, 覆盖三个名称属性:

• name 是用于生成文件名的标识符。

• localname 是索引的节标题。

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

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

generate(docnames=None)

Get entries for the index.

If docnames is given, restrict to entries referring to these docnames.

The return value is a tuple of (content, collapse):

collapse

A boolean that determines if sub-entries should start collapsed (for output formats that support collapsing sub-entries).

content:

一系列 (letter，entries) 元组，其中 letter 是给定 entries 的 “heading”, 通常是起始字母, entries 是一个序列单个条目。 每个条目都是一个序列 [name，subtype，docname，anchor，extra，qualifier，descr]. 此序列中的项目具有以下含义:

name

The name of the index entry to be displayed.

subtype

子条目相关类型。之一:

0

正常进入。

1

包含子条目的条目。

2

一个子条目。

docname

docname where the entry is located.

anchor

Anchor for the entry within docname

extra

Extra info for the entry.

qualifier

Qualifier for the description.

descr

Description for the entry.

Qualifier and description are not rendered for some output formats such as LaTeX.