ドメインAPI

class sphinx.domains.Domain(env: BuildEnvironment)

ドメインというのは、似たような特性を持つオブジェクトごとに用意された「オブジェクト」説明ディレクティブと、それらに対応してリファレンスを作成するロールを集めたものです。例えば、Pythonのモジュール、クラス、関数、テンプレート言語であればエレメント、Sphinxであればロールとディレクティブなどです。

ドメインごとに、既存のオブジェクトの情報や、それらへの参照の仕方などを個別の領域に保存します。保存先は self.data で、辞書でなければなりません。また、Sphinxの一部として決まったフォーマットでオブジェクトの情報を公開するための関数や、ユーザが参照できるようにしたり、ドメインごとの方法でオブジェクトを探索する関数をいくつか実装する必要があります。

About self.data: since all object and cross-referencing information is stored on a BuildEnvironment instance, the domain.data object is also stored in the env.domaindata dict under the key domain.name. Before the build process starts, every active domain is instantiated and given the environment object; the domaindata dict must then either be nonexistent or a dictionary whose 'version' key is equal to the domain class' data_version attribute. Otherwise, OSError is raised and the pickled environment is discarded.

add_object_type(name: str, objtype: sphinx.domains.ObjType) → None

Add an object type.

check_consistency() → None

Do consistency checks (experimental).

clear_doc(docname: str) → None

ドメインに特化した領域から、指定されたドキュメントの情報を削除します。

directive(name: str) → Callable

self.name で指定されたドメイン付きで、完全な名前('ドメイン:名前')で登録されたディレクティブ を与える、ディレクティブアダプタークラスを返します。

get_enumerable_node_type(node: docutils.nodes.Node) → str

Get type of enumerable nodes (experimental).

get_full_qualified_name(node: docutils.nodes.Element) → str

Return full qualified name for given node.

get_objects() → Iterable[Tuple[str, str, str, str, str, int]]

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: sphinx.domains.ObjType, primary: bool = False) → str

与えられたObjTypeの完全な名前を返します。

merge_domaindata(docnames: List[str], otherdata: Dict) → None

Merge in data regarding docnames from a different domaindata inventory (coming from a subprocess in parallel builds).

process_doc(env: BuildEnvironment, docname: str, document: docutils.nodes.document) → None

ドキュメントが環境によって読まれた後で、そのドキュメントを処理します。

process_field_xref(pnode: sphinx.addnodes.pending_xref) → None

Process a pending xref created in a doc field. For example, attach information about the current scope.

resolve_any_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, target: str, node: sphinx.addnodes.pending_xref, contnode: docutils.nodes.Element) → List[Tuple[str, docutils.nodes.Element]]

target を持つ、 pending_xref (未解決のクロスリファレンス) node の参照先の解決を行います。

"any", もしくはそれに類似するロールに基づくリファレンスは、タイプがわからないということを意味します。もしくは、引数が resolve_xref() と同様のものであるかです。

このメソッドはタプルを要素に持つリストを返す必要があります(リストは空の可能性があります)。各要素はタプルで、 ('domain:role', newnode) の形式です。 'domain:role' は 'py:func' のようなnewnodeを生成するときに使われるロール名で、 newnode は resolve_xref() の返値と同じです。

バージョン 1.3 で追加.

resolve_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, typ: str, target: str, node: sphinx.addnodes.pending_xref, contnode: docutils.nodes.Element) → docutils.nodes.Element

typ 型と、 target を持つ、 pending_xref (未解決のクロスリファレンス) node の参照先の解決を行います。

このメソッドは、xrefノードと置き換えるための、新しいノードを返さなければなりません。また、この新しいノードには、クロスリファレンスのマークアップのコンテンツである、 contnode を含めます。

If no resolution can be found, None can be returned; the xref node will then given to the missing-reference event, and if that yields no resolution, replaced by contnode.

The method can also raise sphinx.environment.NoUri to suppress the missing-reference event being emitted.

role(name: str) → Callable[[str, str, str, int, docutils.parsers.rst.states.Inliner, Dict[str, Any], List[str]], Tuple[List[docutils.nodes.Node], List[docutils.nodes.system_message]]]

登録された完全な名前を持つロール('ドメイン:名前')を最初の引数として与える、ロールアダプター関数を返します。

setup() → None

Set up domain object.

dangling_warnings: Dict[str, str] = {}

ロール名 -> リファレンスが存在しないときの警告メッセージ

data: Dict = None

data value

data_version = 0

データのバージョンです。もしも self.data 内のフォーマットを変更したときには、この数字を上げてください。

directives: Dict[str, Any] = {}

ディレクティブ名→ディレクティブのクラスとなる辞書です。

enumerable_nodes: Dict[Type[docutils.nodes.Node], Tuple[str, Callable]] = {}

node_class -> (enum_node_type, title_getter)

indices: List[Type[sphinx.domains.Index]] = []

Indexのサブクラスが格納されたリストです。

initial_data: Dict = {}

新しい環境に入れる値です。

label = ''

ドメインのラベルです。 name よりも長く、説明的な名前です。メッセージ内で利用されます。

name = ''

ドメイン名です。なるべく短く、重複のない名前にする必要があります。

object_types: Dict[str, sphinx.domains.ObjType] = {}

型(通常はディレクティブ)名→ObjTypeのインスタンスとなる辞書です。

roles: Dict[str, Union[Callable[[str, str, str, int, docutils.parsers.rst.states.Inliner, Dict[str, Any], List[str]], Tuple[List[docutils.nodes.Node], List[docutils.nodes.system_message]]], sphinx.roles.XRefRole]] = {}

ロール名→ロールの呼び出し可能オブジェクトとなる辞書です。

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

ObjTypeは、そのドメインでドキュメントを書くことができる、オブジェクトの種類に対する説明ユニットです。Domainのサブクラスの object_types の辞書の中に、オブジェクト名と、このクラスのインスタンスのマッピングが保持されます。

コンストラクタ引数

• lname: ローカライズされた型名

• roles: この型を参照できる、すべてのロール

• attrs: オブジェクトの属性。現在では、全文検索インデックス内での、オブジェクトの優先順位(Domain.get_objects() 参照)のみが定義されています。

class sphinx.domains.Index(domain: sphinx.domains.Domain)

Indexは、ドメインに特化した索引のための説明を行うクラスです。ドメインに対する索引を追加する場合には、Indexのサブクラスを作り、3つの名前属性をオーバーライドします:

• 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 は索引のセクションタイトルです。

• shortname は索引に対する短い名前です。これは、HTML出力のリレーションバーで使用されます。もしも空であれば、リレーションバーのエントリーは無効化されます。

次に、 generate() メソッドを提供するようにします。最後に、自分の作ったドメインのDomainクラスが持つ、 indices リストに追加します。拡張機能の中で add_index_to_domain() メソッドを呼ぶと、既存のドメインに対して、索引を追加することもできます。

バージョン 3.0 で変更: Index pages can be referred by domain name and index name via ref role.

abstract generate(docnames: Optional[Iterable[str]] = None) → Tuple[List[Tuple[str, List[sphinx.domains.IndexEntry]]], bool]

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:

A sequence of (letter, entries) tuples, where letter is the "heading" for the given entries, usually the starting letter, and entries is a sequence of single entries. Each entry is a sequence [name, subtype, docname, anchor, extra, qualifier, descr]. The items in this sequence have the following meaning:

name

The name of the index entry to be displayed.

subtype

The sub-entry related type. One of:

0

A normal entry.

1

An entry with sub-entries.

2

A sub-entry.

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.

Python Domain

class sphinx.domains.python.PythonDomain(env: BuildEnvironment)

Python language domain.

objects

modules

note_object(name: str, objtype: str, node_id: str, canonical: bool = False, location: Optional[Any] = None) → None

Note a python object for cross reference.

バージョン 2.1 で追加.

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

Note a python module for cross reference.

バージョン 2.1 で追加.