ドメイン 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]]

「オブジェクトの説明」のイテラブルを返します。

オブジェクトの説明は、6 つの項目を持つタプルです

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

ドキュメントフィールドで作成された保留中のxrefを処理します。たとえば、現在のスコープに関する情報を付加します。

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()が返すものです。

バージョン1.3で追加。

resolve_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, typ: str, target: str, node: pending_xref, contnode: Element) → Element | None

指定されたtypおよびtargetを使用して、保留中のxref nodeを解決します。

このメソッドは、xrefノードを置き換える新しいノードを返し、そのノードにはクロスリファレンスのマークアップコンテンツであるcontnodeが含まれている必要があります。

解決策が見つからない場合は、Noneを返すことができます。xrefノードは、missing-referenceイベントに渡され、解決策が得られない場合は、contnodeで置き換えられます。

このメソッドは、missing-referenceイベントの発行を抑制するために、sphinx.environment.NoUriを発生させることもできます。

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

ディレクティブ名 -> ディレクティブクラス

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

node_class -> (enum_node_type, title_getter)

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

Index サブクラスのリスト

initial_data: dict = {}

新しい環境のためのデータ値

label = ''

ドメインラベル：より長く、より説明的な（メッセージで使用されます）

name = ''

ドメイン名：短く、かつ一意である必要があります

object_types: dict[str, ObjType] = {}

型（通常はディレクティブ）名 -> ObjTypeインスタンス

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

ロール名 -> ロール呼び出し可能オブジェクト

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は、ドメイン固有のインデックスの説明です。ドメインにインデックスを追加するには、Indexをサブクラス化し、3つの名前属性をオーバーライドします。

• name は、ファイル名の生成に使用される識別子です。また、インデックスのハイパーリンクターゲットにも使用されます。したがって、ユーザーは ref ロールと、ドメイン名と name 属性を組み合わせた文字列を使用して、インデックスページを参照できます（例： :ref:`py-modindex`）。

• localname は、インデックスのセクションタイトルです。

• shortname は、HTML出力の関係バーで使用するためのインデックスの短い名前です。関係バーのエントリを無効にするために空にすることができます。

および generate() メソッドを提供します。次に、インデッククラスをドメインの indices リストに追加します。拡張機能は、add_index_to_domain() を使用して、既存のドメインにインデックスを追加できます。

バージョン 3.0 で変更: インデックスページは、ref ロールを介してドメイン名とインデックス名で参照できます。

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

インデックスのエントリを取得します。

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)

インデックスエントリ。

注釈

qualifier と description は、LaTeX などの一部の出力形式ではレンダリングされません。

name: str

表示するインデックスエントリの名前。

subtype: int

サブエントリ関連のタイプ。以下のいずれか。

0

通常のエントリ。

1

サブエントリを持つエントリ。

2

サブエントリ。

docname: str

エントリがある docname。

anchor: str

docname 内のエントリのアンカー。

extra: str

エントリの追加情報。

qualifier: str

説明の修飾子。

descr: str

エントリの説明。

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() をオーバーライドする必要があります。オブジェクトの階層の各部分に 1 つ（文字列）のエントリを設定します。このメソッドの結果は署名ノードに設定され、このメソッド内で使用するために 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

該当する場合は、相互参照 ID とエントリを self.indexnode に追加します。

name は、handle_signature() が返したものです。

after_content() → None

コンテンツの解析後に呼び出されます。ビルド環境上の現在のディレクティブコンテキストに関する情報をリセットするために使用されます。

before_content() → None

コンテンツの解析前に呼び出されます。ビルド環境上の現在のディレクティブコンテキストに関する情報を設定するために使用されます。

get_signatures() → list[str]

ディレクティブ引数からドキュメント化するシグネチャを取得します。デフォルトでは、シグネチャは引数として、1行に1つずつ指定されます。

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.handle_signature() を使用して、指定されたすべてのシグネチャ（self.get_signatures() が返すもの）を解析します。これは名前を返すか、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

相互参照のためのPythonオブジェクトを記録します。

バージョン 2.1 で追加。

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

相互参照のためのPythonモジュールを記録します。

バージョン 2.1 で追加。

前へ

Docutils markup API

次へ

Parser API