ドメインAPI

class sphinx.domains.Domain(env)[ソース]

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

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

self.data に関しては、すべてのオブジェクトとクロスリファレンス情報はBuildEnvironmentインスタンスに保存しておくために、 domain.data オブジェクトも、 domain.name をキーにして env.domaindata 辞書に格納します。ビルドプロセスが始まるまえに、すべてのアクティブなドメインがインスタンス化され、環境オブジェクトが与えられます。 domaindata 辞書は、空にしておくか、もしくは’version’というキーがドメインクラスの data_version 属性と同じ値を格納しておく必要があります。そうでない場合には IOError が発生し、既存のpickle化された環境が破棄されます。

clear_doc(docname)[ソース]

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

directive(name)[ソース]

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

get_objects()[ソース]

次のような項目を持つ、「オブジェクトの説明」のタプルを返す、繰り返し可能オブジェクトを返します。

  • name – 完全な修飾付きの名前
  • dispname – 検索やリンクの時に表示される名前
  • type – オブジェクトの種類。 self.object_types のキー
  • docname – そのオブジェクトが発見されたドキュメント名
  • anchor – そのオブジェクトのアンカー名
  • priority – そのオブジェクトがどれだけ重要か?(検索結果の決定に利用される)
    • 1: デフォルトの優先順位(全文検索マッチの前に置かれる)
    • 0: 重要なオブジェクト(出フィルとの優先順位のオブジェクトの前に置かれる)
    • 2: 重要でないオブジェクト(全文検索マッチの後に置かれる)
    • -1: 検索結果に出すべきではないオブジェクト
get_type_name(type, primary=False)[ソース]

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

merge_domaindata(docnames, otherdata)[ソース]

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

process_doc(env, docname, document)[ソース]

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

process_field_xref(pnode)[ソース]

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

resolve_any_xref(env, fromdocname, builder, target, node, contnode)[ソース]

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

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

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

バージョン 1.3 で追加.

resolve_xref(env, fromdocname, builder, typ, target, node, contnode)[ソース]

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

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

もし、参照先を見つけることができなければ、Noneを返すことができます。xrefノードは’missing-reference’イベントを発行し、それでも解決しなければ、 contnode に置き換えられます。

また、このメソッド内で sphinx.environment.NoUri 例外を発生させると、’missing-reference’が発行されるのを押さえることができます。

role(name)[ソース]

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

dangling_warnings = {}

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

data_version = 0

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

directives = {}

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

indices = []

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

initial_data = {}

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

label = ''

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

name = ''

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

object_types = {}

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

roles = {}

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

class sphinx.domains.ObjType(lname, *roles, **attrs)[ソース]

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

コンストラクタ引数

  • lname: ローカライズされた型名
  • roles: この型を参照できる、すべてのロール
  • attrs: オブジェクトの属性。現在では、全文検索インデックス内での、オブジェクトの優先順位(Domain.get_objects() 参照)のみが定義されています。
class sphinx.domains.Index(domain)[ソース]

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

  • name はファイル名を生成する際に使用される、識別子です。
  • localname は索引のセクションタイトルです。
  • shortname は索引に対する短い名前です。これは、HTML出力のリレーションバーで使用されます。もしも空であれば、リレーションバーのエントリーは無効化されます。

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

generate(docnames=None)[ソース]

name が与えられた索引に対する索引のエントリーを返します。もしも docnames が与えられた場合には、これらのdocnameに関連する要素だけを返します。

返り値は (content, collapse) というタプルです。 collapse はブーリアン型で、サブエントリーが折りたたまれて始まるべきかどうかを決定します。(出力フォーマットが折りたたまれたサブエントリーをサポートしている場合)。

content(letter, entries) というタプルです。 letter は与えられた entries の見出しで、通常は初めの文字を表します。

entries は単独のエントリーのシーケンスで、それぞれのエントリーは、 [name, subtype, docname, anchor, extra, qualifier, descr] という要素で構成されます。このシーケンスの要素はそれぞれ次のような意味を持っています。

  • name – 索引のエントリーの、表示される名前
  • subtype – サブエントリーの種類 0 – 通常のエントリー 1 – サブエントリー付きのエントリーentry with sub-entries 2 – サブエントリー
  • docname – エントリーが置かれているドキュメント名
  • anchordocname 内の、エントリーへのアンカー
  • extra – エントリーに関する追加情報extra info for the entry
  • qualifier – 説明の修飾子qualifier for the description
  • descr – エントリーの説明

修飾子と説明はLaTeX出力などではレンダリングされません。