それぞれのsphinx拡張は、最低でも setup() 関数を一つ持っている、Pythonモジュールです。この関数は初期化時に一つの引数を伴って呼び出されます。この引数はapplicationオブジェクトで、Sphinxのプロセスに関する情報を持っています。このapplicationオブジェクトは、以下のような公開APIを持っています:
新しい設定値を登録します。Sphinxが新しい設定値を認識して、関連するデフォルト値を設定するのに必要になります。名前の衝突を回避するために、 name には必ず、拡張機能名を最初に入れてください。 default 値には、Pythonであれば自由に設定することが可能です。 rebuild の値は文字列で、以下の値のうちの一つを取ります。
バージョン 0.4 で変更: もしも default の値が呼び出し可能オブジェクトの場合には、設定オブジェクトを引数に渡して呼び出しを行い、デフォルト値を取得します。これは、他の値に依存してデフォルト値を変更したい場合に使用することができます。
バージョン 0.6 で変更: rebuild が単純なブーリアン型('', 'env' に相当)から文字列に変更されました。後方互換性のために、ブーリアン型も受け取ることが可能で、その場合には内部で変換されます。
Docutilsのノードクラスを登録します。これはDocutils内部で使用するために必要です。将来的にはパースされたドキュメントにおける、ノード検証に使用されるかもしれません。
キーワード引数を使用することで、SphinxのHTMLや、LaTeX, テキストなど、出力形式ごとにノードのビジター関数を与えることができます。キーワードは 'html', 'latex', 'text' のうちの一つ以上で、値としては、ノードに入ったときと出力したときのメソッドをそれぞれ１つずつ含む２要素のタプルを指定します。 depart には、 None を指定可能ですが、この場合は、 visit 関数は docutils.nodes.SkipNode 例外を発生させます。
サンプル:
class math(docutils.nodes.Element)
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))
もちろん、ビジターメソッドを定義しないトランスレータで実行していて、変換すべきドキュメントに遭遇するとビジターメソッドは沈黙します。
バージョン 0.5 で変更: ビジター関数を、キーワード引数を使って渡すことができるようになりました。
Docutilsのディレクティブを登録します。 name は、ディレクティブ名として今後使っていく名前を設定します。ディレクティブを書く方法には、以下の２通りあります:
docutils 0.4スタイル: func がディレクティブ関数で、 content, arguments, *options は関数の属性として設定されます。そして、ディレクティブがコンテンツや引数、オプションを持っているか、それぞれ決定されます。
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)
バージョン 0.6 で変更: Docutils 0.5スタイルのディレクティブクラスがサポートされました。
Docutilsのロールを登録します。このロールは特に何もしませんが、与えられた nodeclass を使ってラップされるようになります。
バージョン 0.6 で追加.
このメソッドは、クロスリファレンスを作成することができる、新しい情報のタイプを追加することができる便利なメソッドです。このメソッドは以下のことを行います:
以下のような関数呼び出しが、カスタムのSphinx拡張の中で行われたとすると:
app.add_description_unit('directive', 'dir', 'pair: %s; directive')
ドキュメント内で以下のようなマークアップが使用できるようになります:
.. directive:: function
functionの説明。
<...>
:dir:`function` ディレクティブも参照してください
また、このディレクティブを使用すると、以下のようにindexディレクティブを書いたのと同じ索引が作成されます:
.. index:: pair: function; directive
リファレンスノードのクラスは、 参照ノードクラス を指定しない場合には literal になります。このクラスはコードの記述に適したプロポーショナルフォントでレンダリングされます。クラスは、docutilsのノードクラスを設定する必要があります。docutilsのクラスの中で頻繁に使用されるのは docutils.nodes.emphasis あるいは docutils.nodes.strong です。もしも装飾が不要であれば、 docutils.nodes.generated を使用することもできます。
ロールの中身に関しては、標準のSphinxのロールと同じオプションを使用することができます(クロスリファレンス文法 参照)。
このメソッドは ディレクティブの出力が必ず空になることを除けば、 add_description_unit() と非常に良く似ています。
これは、セマンティックのターゲットをソースに追加して、カスタムのロールを使用して参照することができるということを意味しています。ただし、 ref のような一般的なものは使用することができません。
サンプル:
app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)
使用例:
.. topic:: application API
アプリケーション API
-------------------
<...>
:topic:`このセクション <application API>` を参照してください。
もちろん、 topic ディレクティブに続く要素はセクションでなくてもかまいません。
JavaScriptのファイルのリストに、指定された filename のファイルを追加します。ここで指定されたファイルは、デフォルトのHTMLテンプレートの中にインクルードされます。ファイル名はHTMLの静的パスへの相対パスでなければなりません。詳しくは 設定値のドキュメント を参照してください。
バージョン 0.5 で追加.
alias で指定された言語で書かれたコードブロックのハイライトを行う、Pygmentsのレキサークラスのインスタンス lexer を設定します。
バージョン 0.6 で追加.
sphinx.ext.autodoc 拡張のための新しいドキュメンタークラスとして、 cls クラスを追加します。この引数は sphinx.ext.autodoc.Documenter のサブクラスでなければなりません。これによって、新しいタイプのオブジェクトの自動ドキュメントが可能になります。どのように Documenter のサブクラスを作ればいいのか、というサンプルを参照したい場合には、autodocモジュールのソースコードを参照してください。
バージョン 0.6 で追加.
組み込みの getattr() 関数と互換性のあるインタフェースを持つ、 getter 関数を追加します。これは type 型のインスタンスのオブジェクトから、自動的に属性を取得してドキュメントを作成するのに使用されます。autodocが型の属性を取得する必要がある場面では、標準の getattr() 関数の代わりに、ここで指定された関数が呼ばれます。
バージョン 0.6 で追加.
event が発行されたときに呼ばれる、 callback を登録します。利用可能なコアイベントと、コールバック関数の引数の詳細情報に関しては Sphinxコアイベント を参照してください。
このメソッドは “リスナーID” を返します。これは disconnect() を呼んで削除する場合の引き数に使用します。
event を発行します。コールバック関数には arguments が渡されます。最初に None 以外を返したコールバックの返り値を返します。それ以降の残りのコールバックは呼ばれません。
バージョン 0.5 で追加.
Sphinx拡張APIの使用法に関するサンプルは、Sphinx標準の sphinx.ext のパッケージの中を見てください。
これから説明するイベントがコアイベントです。ここで示した引数は、登録されたイベントハンドラに渡されます。
ソースファイルが削除されたり、新たに読み込まる場合など、環境の中に含まれるソースファイルの関連情報をクリアすべき状況になった場合に発行されます。環境の属性の中に情報をキャッシュしておくような拡張機能ためのイベントです。
例えば、環境の中にすべてのモジュールのキャッシュが存在してる場合、ソースファイルが変更されると、ファイルからモジュール宣言から削除されてから、そのファイルに関するキャッシュのエントリーはクリアされます。
バージョン 0.5 で追加.
ソースファイルが読み込まれる時に発行されます。 source 引数はリストで、ひとつの要素はソースファイルのコンテンツを表します。コンテンツに関する処理を行ったり、要素に関してソースレベルでの変換を実装したりすることができます。
もしも、LaTeXと同じように、 $ 記号を、インラインの数式の区切り文字にしたい場合には、このイベントハンドラの中で、正規表現を使用して $...$ を :math:`...` に置き換えることで実現することができます。
バージョン 0.5 で追加.
Pythonモジュールやオブジェクトへの相互参照が解決できないときに発行されます。もしも参照の問題を解決できる場合には、 node の代わりにドキュメントツリーに挿入される、新しいdocutilsのノードを返すことで、イベントハンドラ側で解決を行うことができます。通常このノードは、 contnode を子供として含む reference ノードです。
| パラメタ: |
|
|---|
環境がdoctreeに関して”resolved(解決)”と判断したときに発行されます。これは、すべての参照が解決され、目次が挿入された時、ということになります。 doctree はこのイベントハンドラないで操作することができます。
このイベントは、ライタークラスにビジターメソッドが存在しない、カスタムのノードを置換して処理するのに使用することができます。もしもここで設定しない場合、未知のノードを見つけると、ライターはエラーを出しますが、設定することでエラーが出なくなります。
ビルダーの update() メソッドの実行が完了し、環境とすべてのdoctreeが最新になった時に発行されます。
バージョン 0.5 で追加.
HTMLビルダーがコンテキストの辞書を作り、テンプレートを使用してレンダリングを行う時に発行されます。このイベントは、追加のカスタムの要素をコンテキストに追加する場合に使用することができます。
pagename 引数はレンダリングされるページの、規範に則った名前です。規範というのは、 .html が付かず、パス区切りとしてスラッシュ(/)が使われている状態です。 templatename はレンダリングに使用するテンプレートの名前です。 reSTドキュメントのページのレンダリング時には、必ず 'page.html' となります。
context 引数はテンプレートエンジンがページをレンダリングする際に与えられる値の辞書になります。カスタムの値を持つように、変更することが可能です。キーは必ず文字列です。
doctree 引数はreSTドキュメントから作成する場合にはdoctreeとなります。もしもHTMLテンプレートからのみ作成されるページの場合には、 None となります。
バージョン 0.4 で追加.
ビルドが完了し、Sphinxが終了する際に発行されます。通常はクリーンアップに使用されます。このイベントは、ビルドプロセスが例外を上げたときにも発行されます。その場合には、 exception 引数が渡されます。アプリケーションの中で発生した例外は、このイベントハンドラが終了した段階で、再度投げられます。もしもビルドプロセスが例外を発生しなかった場合には、 exception は None になります。これによって、例外の種類ごとの、クリーンアップの処理をカスタム化できます。
バージョン 0.5 で追加.
このクラスは、”テンプレートへのブリッジ”をっ定義しています。テンプレートブリッジというのは、与えられたテンプレート名と、コンテキストを利用して、テンプレートをレンダリングするクラスのことです。
テンプレートのシステムの初期化を行うために、ビルダーから呼ばれます。
builder はビルダーオブジェクトで、 builder.config.templates_path の値を使用することになるでしょう。
theme は sphinx.theming.Theme オブジェクト、あるいは None になります。後者の場合には、 dirs に固定ディレクトリのパスが入ったリストが渡され、この中からテンプレートを探します。