それぞれのsphinx拡張は、最低でも setup() 関数を一つ持っている、Pythonモジュールです。この関数は初期化時に一つの引数を伴って呼び出されます。この引数はapplicationオブジェクトで、Sphinxのプロセスに関する情報を持っています。このapplicationオブジェクトは、以下のような公開APIを持っています:
name に与えられた名前を持っている拡張機能をロードします。もしも、作成中の拡張機能が、他の拡張の機能を利用している場合に、このメソッドを使用してください。
新しい設定値を登録します。Sphinxが新しい設定値を認識して、関連するデフォルト値を設定するのに必要になります。名前の衝突を回避するために、 name には必ず、拡張機能名を最初に入れてください。 default 値には、Pythonであれば自由に設定することが可能です。 rebuild の値は文字列で、以下の値のうちの一つを取ります。
Changed in version 0.4: もしも default の値が呼び出し可能オブジェクトの場合には、設定オブジェクトを引数に渡して呼び出しを行い、デフォルト値を取得します。これは、他の値に依存してデフォルト値を変更したい場合に使用することができます。
Changed in version 0.6: rebuild が単純なブーリアン型('', 'env' に相当)から文字列に変更されました。後方互換性のために、ブーリアン型も受け取ることが可能で、その場合には内部で変換されます。
与えられた domain (クラスです。おそらく Domain のサブクラスになるでしょう)をSphinxに知らせます。
New in version 1.0.
与えられた domain クラスをSphinxに知らせますが、指定されたクラスの .name 属性がすでに登録されている場合に使用します。新しい domain クラスは、既存のクラスのサブクラスでなければなりません。
New in version 1.0.
カスタムの index クラスを、 domain で指定されたドメイン名に追加します。 index は Index のサブクラスでなければなりません。
New in version 1.0.
name で指定された名前を持つイベントを登録します。イベントを発行するためには、登録しなければなりません。
Docutilsのノードクラスを登録します。これはDocutils内部で使用するために必要です。将来的にはパースされたドキュメントにおける、ノード検証に使用されるかもしれません。
キーワード引数を使用することで、SphinxのHTMLや、LaTeX、テキスト、manページなど、出力形式ごとにノードのビジター関数を与えることができます。キーワードは 'html', 'latex', 'text', 'man' のうちの一つ以上で、値としては、ノードに入ったときと出力したときのメソッドをそれぞれ１つずつ含む２要素のタプルを指定します。 depart には、 None を指定可能ですが、この場合は、 visit 関数は docutils.nodes.SkipNode 例外を発生させます:
class math(docutils.nodes.Element): pass
def visit_math_html(self, node):
self.body.append(self.starttag(node, 'math'))
def depart_math_html(self, node):
self.body.append('</math>')
app.add_node(math, html=(visit_math_html, depart_math_html))
もちろん、ビジターメソッドを定義しないトランスレータで実行していて、変換すべきドキュメントに遭遇するとビジターメソッドは沈黙します。
Changed in version 0.5: ビジター関数を、キーワード引数を使って渡すことができるようになりました。
Docutilsのディレクティブを登録します。 name は、ディレクティブ名として今後使っていく名前を設定します。ディレクティブを書く方法には、以下の２通りあります:
docutils 0.5スタイル: has_content, required_arguments, optional_arguments, final_argument_whitespace, option_spec という、必要な属性を初めから持った、 directiveclass という、ディレクティブのためのクラスで定義します。これらの属性は、関数で登録する方法と同じ役割を持っています。詳しくは、 Docutilsの資料 をご覧ください。
ディレクティブクラスは通常、docutils.parsers.rst.Directiveクラスを継承しなければなりません。Sphinxの拡張機能を作成するために、ディレクティブを書く場合は、sphinx.util.compat.Directiveクラスを継承してください。こちらのクラスであれば、ディレクティブクラスをサポートしていない、Docutils 0.4でも正しく動作します。
例えば、 literalinclude というディレクティブを追加する場合には(既に存在していますが)、以下のように書きます:
from docutils.parsers.rst import directives
add_directive('literalinclude', literalinclude_directive,
content = 0, arguments = (1, 0, 0),
linenos = directives.flag,
language = direcitves.unchanged,
encoding = directives.encoding)
Changed in version 0.6: Docutils 0.5スタイルのディレクティブクラスがサポートされました。
add_directive() と似ていますが、ディレクティブを、 domain で指定されたドメインにのみ追加します。
New in version 1.0.
Docutilsのロールを登録します。 name はドキュメントのソースに表示されるロール名でなければなりません。 role はロールの関数を指定します。詳しくは Docutilsのドキュメント を参照してください。
add_role() に似ていますが、 domain で指定されたドメインに、新しいロールを追加します。
New in version 1.0.
Docutilsのロールを登録します。このロールは特に何もしませんが、与えられた nodeclass を使ってラップされるようになります。
New in version 0.6.
このメソッドは、クロスリファレンスを作成することができる、新しい情報のタイプを追加することができる便利なメソッドです。このメソッドは以下のことを行います:
以下のような関数呼び出しが、カスタムのSphinx拡張の中で行われたとすると:
app.add_object_type('directive', 'dir', 'pair: %s; directive')
ドキュメント内で次のようなマークアップが使用できるようになります:
.. rst:directive:: function
functionの説明。
<...>
:rst:dir:`function` ディレクティブも参照してください
また、このディレクティブを使用すると、以下のようにindexディレクティブを書いたのと同じ索引が作成されます:
.. index:: pair: function; directive
リファレンスノードのクラスは、 参照ノードクラス を指定しない場合には literal になります。このクラスはコードの記述に適したプロポーショナルフォントでレンダリングされます。クラスは、docutilsのノードクラスを設定する必要があります。docutilsのクラスの中で頻繁に使用されるのは docutils.nodes.emphasis あるいは docutils.nodes.strong です。もしも装飾が不要であれば、 docutils.nodes.generated を使用することもできます。
ロールの中身に関しては、標準のSphinxのロールと同じ構文を使用することができます(クロスリファレンス文法 参照)。
このメソッドは旧名の :meth:add_description_unit という名前でも呼び出すことができます。
このメソッドは ディレクティブの出力が必ず空になることを除けば、 add_object_type() と非常に良く似ています。
これは、セマンティックのターゲットをソースに追加して、カスタムのロールを使用して参照することができるということを意味しています。ただし、 ref のような一般的なものは使用することができません。
サンプル:
app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)
使用例:
.. topic:: application API
アプリケーション API
-------------------
<...>
:topic:`このセクション <application API>` を参照してください。
もちろん、 topic ディレクティブに続く要素はセクションでなくてもかまいません。
標準のDocutilsの Transform のサブクラスの transform をtransformのリストに追加します。これはSphinxがreST形式のドキュメントをパースした後に適用されます。
JavaScriptのファイルのリストに、指定された filename のファイルを追加します。ここで指定されたファイルは、デフォルトのHTMLテンプレートの中にインクルードされます。ファイル名はHTMLの静的パスへの相対パスでなければなりません。詳しくは 設定値のドキュメント を参照してください。
New in version 0.5.
CSSのファイルのリストに、指定された filename のファイルを追加します。ここで指定されたファイルは、デフォルトのHTMLテンプレートの中にインクルードされます。 add_javascript() と同様に、ファイル名はHTMLの静的パスへの相対パスでなければなりません。
New in version 1.0.
alias で指定された言語で書かれたコードブロックのハイライトを行う、Pygmentsのレキサークラスのインスタンス lexer を設定します。
New in version 0.6.
sphinx.ext.autodoc 拡張のための新しいドキュメンタークラスとして、 cls クラスを追加します。この引数は sphinx.ext.autodoc.Documenter のサブクラスでなければなりません。これによって、新しいタイプのオブジェクトの自動ドキュメントが可能になります。どのように Documenter のサブクラスを作ればいいのか、というサンプルを参照したい場合には、autodocモジュールのソースコードを参照してください。
New in version 0.6.
組み込みの getattr() 関数と互換性のあるインタフェースを持つ、 getter 関数を追加します。これは type 型のインスタンスのオブジェクトから、自動的に属性を取得してドキュメントを作成するのに使用されます。autodocが型の属性を取得する必要がある場面では、標準の getattr() 関数の代わりに、ここで指定された関数が呼ばれます。
New in version 0.6.
event が発行されたときに呼ばれる、 callback を登録します。利用可能なコアイベントと、コールバック関数の引数の詳細情報に関しては Sphinxコアイベント を参照してください。
このメソッドは “リスナーID” を返します。これは disconnect() を呼んで削除する場合の引き数に使用します。
listener_id で指定されたコールバックの登録を解除します。
event を発行します。コールバック関数には arguments が渡されます。返り値は、すべてのコールバックの返り値がリストに格納されて返されます。拡張機能の中からは、Sphinxのコアのイベントを発行しないでください。
event を発行します。コールバック関数には arguments が渡されます。最初に None 以外を返したコールバックの返り値を返します。
New in version 0.5.
version ('1.1' のような、 メジャー.マイナー 形式のバージョン文字列)と、実行しているSphinxのバージョンを比較して、古すぎる場合にはビルドを中断します。
New in version 1.0.
ここで説明したすべての関数は、もし拡張APIの中で何か想定外のことが発生した時には、この例外を投げます。
Sphinx拡張APIの使用法に関するサンプルは、Sphinx標準の sphinx.ext のパッケージの中を見てください。
これから説明するイベントがコアイベントです。ここで示した引数は、登録されたイベントハンドラに渡されます。
ビルダーオブジェクトが作成された時に発行されます。ビルダーオブジェクトは app.builder とすることで参照できます。
ソースファイルが削除されたり、新たに読み込まる場合など、環境の中に含まれるソースファイルの関連情報をクリアすべき状況になった場合に発行されます。環境の属性の中に情報をキャッシュしておくような拡張機能ためのイベントです。
例えば、環境の中にすべてのモジュールのキャッシュが存在してる場合、ソースファイルが変更されると、ファイルからモジュール宣言から削除されてから、そのファイルに関するキャッシュのエントリーはクリアされます。
New in version 0.5.
ソースファイルが読み込まれる時に発行されます。 source 引数はリストで、ひとつの要素はソースファイルのコンテンツを表します。コンテンツに関する処理を行ったり、要素に関してソースレベルでの変換を実装したりすることができます。
もしも、LaTeXと同じように、 $ 記号を、インラインの数式の区切り文字にしたい場合には、このイベントハンドラの中で、正規表現を使用して $...$ を :math:`...` に置き換えることで実現することができます。
New in version 0.5.
doctreeがパースされ、環境から読み込まれ、pickle化される時に発行されます。 doctree をその場で変更することができます。
Pythonモジュールやオブジェクトへの相互参照が解決できないときに発行されます。もしも参照の問題を解決できる場合には、 node の代わりにドキュメントツリーに挿入される、新しいdocutilsのノードを返すことで、イベントハンドラ側で解決を行うことができます。通常このノードは、 contnode を子供として含む reference ノードです。
| Param env: | ビルド環境(app.builder.env) |
|---|---|
| Param node: | 未解決の、解決すべき pending_xref ノードです。このノードは、参照を解決するために、 reftype, reftarget, modname, classname といった、型とターゲットに関する情報を属性として持ちます。 |
| Param contnode: | このノードは、将来の参照が持つ、テキストとフォーマット情報を持ちます。これは返される参照ノードの子供にならなければなりません。 |
環境がdoctreeに関して”resolved(解決)”と判断したときに発行されます。これは、すべての参照が解決され、目次が挿入された時、ということになります。 doctree はこのイベントハンドラ内で操作することができます。
このイベントは、ライタークラスにビジターメソッドが存在しない、カスタムのノードを置換して処理するのに使用することができます。もしもここで設定しない場合、未知のノードを見つけると、ライターはエラーを出しますが、設定することでエラーが出なくなります。
ビルダーの update() メソッドの実行が完了し、環境とすべてのdoctreeが最新になった時に発行されます。
New in version 0.5.
HTMLビルダーが、ドキュメント以外のページの書き込みを開始するときに発行されます。 (ページ名, コンテキスト, テンプレート名) という構成の要素を含むシーケンスを返すと、ページを追加することができます。
New in version 1.0.
HTMLビルダーがコンテキストの辞書を作り、テンプレートを使用してレンダリングを行う時に発行されます。このイベントは、追加のカスタムの要素をコンテキストに追加する場合に使用することができます。
pagename 引数はレンダリングされるページの、規範に則った名前です。規範というのは、 .html が付かず、パス区切りとしてスラッシュ(/)が使われている状態です。 templatename はレンダリングに使用するテンプレートの名前です。 reSTドキュメントのページのレンダリング時には、必ず 'page.html' となります。
context 引数はテンプレートエンジンがページをレンダリングする際に与えられる値の辞書になります。カスタムの値を持つように、変更することが可能です。キーは必ず文字列です。
doctree 引数はreSTドキュメントから作成する場合にはdoctreeとなります。もしもHTMLテンプレートからのみ作成されるページの場合には、 None となります。
New in version 0.4.
ビルドが完了し、Sphinxが終了する際に発行されます。通常はクリーンアップに使用されます。このイベントは、ビルドプロセスが例外を上げたときにも発行されます。その場合には、 exception 引数が渡されます。アプリケーションの中で発生した例外は、このイベントハンドラが終了した段階で、再度投げられます。もしもビルドプロセスが例外を発生しなかった場合には、 exception は None になります。これによって、例外の種類ごとの、クリーンアップの処理をカスタム化できます。
New in version 0.5.
このクラスは、”テンプレートへのブリッジ”を定義しています。テンプレートブリッジというのは、与えられたテンプレート名と、コンテキストを利用して、テンプレートをレンダリングするクラスのことです。
テンプレートのシステムの初期化を行うために、ビルダーから呼ばれます。
builder はビルダーオブジェクトで、 builder.config.templates_path の値を使用することになるでしょう。
theme は sphinx.theming.Theme オブジェクト、あるいは None になります。後者の場合には、 dirs に固定ディレクトリのパスが入ったリストが渡され、この中からテンプレートを探します。
このメソッドはビルダーから呼ばれます。テンプレートが変更されたことで、出力ファイルを再レンダリングする必要があるかどうかの判断をするために使用されます。変更された、最新のテンプレートのmtimeを返します。デフォルトの実装ではゼロを返します。
指定された context (Python辞書)を使用して、 template で指定されたファイル名のテンプレートのレンダリングを行います。ビルダーから呼ばれます。
指定された context (Python辞書)を使用して、 template で指定された文字列形式のテンプレートのレンダリングを行います。ビルダーから呼ばれます。
ドメインというのは、似たような特性を持つオブジェクトごとに用意された「オブジェクト」説明ディレクティブと、それらに対応してリファレンスを作成するロールを集めたものです。例えば、Pythonのモジュール、クラス、関数、テンプレート言語であればエレメント、Sphinxであればロールとディレクティブなどです。
ドメインごとに、既存のオブジェクトの情報や、それらへの参照の仕方などを個別の領域に保存します。保存先は self.data で、辞書でなければなりません。また、Sphinxの一部として決まったフォーマットでオブジェクトの情報を公開するための関数や、ユーザが参照できるようにしたり、ドメインごとの方法でオブジェクトを探索したりする関数をいくつか実装する必要があります。
self.data に関しては、すべてのオブジェクトとクロスリファレンス情報はBuildEnvironmentインスタンスに保存しておくために、 domain.data オブジェクトも、 domain.name をキーにして env.domaindata 辞書に格納します。ビルドプロセスが始まるまえに、すべてのアクティブなドメインがインスタンス化され、環境オブジェクトが与えられます。 domaindata 辞書は、空にしておくか、もしくは’version’というキーがドメインクラスの data_version 属性と同じ値を格納しておく必要があります。そうでない場合には IOError が発生し、既存のpickle化された環境が破棄されます。
ドメインに特化した領域から、指定されたドキュメントの情報を削除します。
self.name で指定されたドメイン付きで、完全な名前(‘ドメイン:名前’)で登録されたディレクティブ を与える、ディレクティブアダプタークラスを返します。
次のような項目を持つ、「オブジェクトの説明」のタプルを返す、繰り返し可能オブジェクトを返します。
typ 型と、 target を持つ、 pending_xref (未解決のクロスリファレンス) node の参照先の解決を行います。
このメソッドは、xrefノードと置き換えるための、新しいノードを返さなければなりません。また、この新しいノードには、クロスリファレンスのマークアップのコンテンツである、 contnode を含めます。
もし、参照先を見つけることができなければ、Noneを返すことができます。xrefノードは’missing-reference’イベントを発行し、それでも解決しなければ、 contnode に置き換えられます。
また、このメソッド内で sphinx.environment.NoUri 例外を発生させると、’missing-reference’が発行されるのを押さえることができます。
登録された完全な名前を持つロール(‘ドメイン:名前’)を最初の引数として与える、ロールアダプター関数を返します。
データのバージョンです。もしも self.data 内のフォーマットを変更したときには、この数字を上げてください。
ディレクティブ名→ディレクティブのクラスとなる辞書です。
Indexのサブクラスが格納されたリストです。
新しい環境に入れる値です。
ドメインのラベルです。 name よりも長く、説明的な名前です。メッセージ内で利用されます。
ドメイン名です。なるべく短く、重複のない名前にする必要があります。
型(通常はディレクティブ)名→ObjTypeのインスタンスとなる辞書です。
ロール名→ロールの呼び出し可能オブジェクトとなる辞書です。
ObjTypeは、そのドメインでドキュメントを書くことができる、オブジェクトの種類に対する説明ユニットです。Domainのサブクラスの object_types の辞書の中に、オブジェクト名と、このクラスのインスタンスのマッピングが保持されます。
コンストラクタ引数
Indexは、ドメインに特化した索引のための説明を行うクラスです。ドメインに対する索引を追加する場合には、Indexのサブクラスを作り、3つの名前属性をオーバーライドします:
次に、 generate() メソッドを提供するようにします。最後に、自分の作ったドメインのDomainクラスが持つ、 indices リストに追加します。拡張機能の中で add_index_to_domain() メソッドを呼ぶと、既存のドメインに対して、索引を追加することもできます。
name が与えられた索引に対する索引のエントリーを返します。もしも docnames が与えられた場合には、これらのdocnameに関連する要素だけを返します。
返り値は (content, collapse) というタプルです。 collapse はブーリアン型で、サブエントリーが折りたたまれて始まるべきかどうかを決定します。(出力フォーマットが折りたたまれたサブエントリーをサポートしている場合)。
content は (etter, entries) というタプルです。 letter は与えられた entries の見出しで、通常は初めの文字を表します。
entries は単独のエントリーのシーケンスで、それぞれのエントリーは、 [name, subtype, docname, anchor, extra, qualifier, descr] という要素で構成されます。このシーケンスの要素はそれぞれ次のような意味を持っています。
修飾子と説明はLaTeX出力などではレンダリングされません。