アプリケーションAPI

それぞれのSphinx拡張は、最低でも setup() 関数を一つ持っている、Pythonモジュールです。この関数は初期化時に一つの引数を伴って呼び出されます。この引数はapplicationオブジェクトで、Sphinxのプロセスに関する情報を持っています。

class sphinx.application.Sphinx[ソース]

Sphinxオブジェクトは以下のようなAPIを持っています

拡張のセットアップ

以下のメソッドは通常、拡張機能のsetup()関数の中で呼ばれます。

Sphinx拡張APIの使用法に関するサンプルは、Sphinx標準の sphinx.ext のパッケージの中を見てください。

Sphinx.setup_extension(name)[ソース]

name に与えられた名前を持っている拡張機能をロードします。もしも、作成中の拡張機能が、他の拡張の機能を利用している場合に、このメソッドを使用してください。

Sphinx.add_builder(builder)[ソース]

新しいビルダーを登録します。 builder 引数は Builder クラスを継承してクラスでなければなりません。

Sphinx.add_config_value(name, default, rebuild)[ソース]

新しい設定値を登録します。Sphinxが新しい設定値を認識して、関連するデフォルト値を設定するのに必要になります。名前の衝突を回避するために、 name には必ず、拡張機能名を最初に入れてください。 default 値には、Pythonであれば自由に設定することが可能です。 rebuild の値は文字列で、以下の値のうちの一つを取ります。

  • 'env' 設定を変更してからビルドをかけると、環境全体が再ビルドされます。

  • 'html' この設定を変更してからビルドをかけた場合、出力がHTMLの時にフル再ビルドされます。

  • '' 設定を変更してもなにも再ビルドに関しては影響を与えません。

バージョン 0.4 で変更: もしも default の値が呼び出し可能オブジェクトの場合には、設定オブジェクトを引数に渡して呼び出しを行い、デフォルト値を取得します。これは、他の値に依存してデフォルト値を変更したい場合に使用できます。

バージョン 0.6 で変更: rebuild が単純なブーリアン型('', 'env' に相当)から文字列に変更されました。後方互換性のために、ブーリアン型も受け取ることが可能で、その場合には内部で変換されます。

Sphinx.add_domain(domain)[ソース]

与えられた domain (クラスです。おそらく Domain のサブクラスになるでしょう)をSphinxに知らせます。

バージョン 1.0 で追加.

Sphinx.override_domain(domain)[ソース]

与えられた domain クラスをSphinxに知らせますが、指定されたクラスの .name 属性がすでに登録されている場合に使用します。新しい domain クラスは、既存のクラスのサブクラスでなければなりません。

バージョン 1.0 で追加.

Sphinx.add_index_to_domain(domain, index)[ソース]

カスタムの index クラスを、 domain で指定されたドメイン名に追加します。 indexIndex のサブクラスでなければなりません。

バージョン 1.0 で追加.

Sphinx.add_event(name)[ソース]

name で指定された名前を持つイベントを登録します。イベントを発行するためには、登録しなければなりません。

Sphinx.set_translator(name, translator_class)[ソース]

Docutilsのトランスレータクラスを登録または上書きします。カスタム出力トランスレータを登録したい場合や、ビルトインのトランスレータを置き換えたい場合に使用します。このメソッドを使って、拡張機能でカスタムトランスレータを使ったり、トランスレータに対してカスタムノードを定義したりすることができます。(参考:add_node())

このメソッドは、設定ファイルの html_translator_class のAPI版で、html以外のビルド設定をするためのものです。留意すべきこととして、html_translator_classが指定されていて、このAPIがHTMLビルダー向けに呼ばれた場合には、API呼び出しのほうが優先されるということです。

バージョン 1.3 で追加.

Sphinx.add_node(node, **kwds)[ソース]

Docutilsのノードクラスを登録します。これはDocutils内部で使用するために必要です。将来的にはパースされたドキュメントにおける、ノード検証に使用されるかもしれません。

キーワード引数を使用することで、SphinxのHTMLや、LaTeX、テキスト、manページなど、出力形式ごとにノードのビジター関数を与えることができます。キーワードは 'html', 'latex', 'text', 'man', 'texinfo', または他のサポートされているトランスレーターを1つ以上指定し、値としては、2要素のタプル (visit, depart) を指定します。 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))

言うまでも無いことですが、ビジターメソッドを定義しないトランスレータを実行していて、そのメソッドを必要とするドキュメントに遭遇するとトランスレータはエラー停止します。

バージョン 0.5 で変更: ビジター関数を、キーワード引数を使って渡すことができるようになりました。

Sphinx.add_enumerable_node(node, figtype, title_getter=None, **kwds)[ソース]

Docutilsのノードクラスをnumfigターゲットとして登録します。Sphinxはノードに自動的に附番します。ユーザーは:rst:role:numref によりこれを参照することができます。

figtype is a type of enumerable nodes. Each figtypes have individual numbering sequences. As a system figtypes, figure, table and code-block are defined. It is able to add custom nodes to these default figtypes. It is also able to define new custom figtype if new figtype is given.

title_getter はノードのタイトルを取得するためのgetter関数です。この関数は連番を行うノードのインスタンスを引数にとり、そのタイトルを文字列として返さなくてはいけません。このタイトルは:rst:role:ref により参照した場合に表示されるデフォルトのタイトルになります。指定しない場合、Sphinxはノードから``docutils.nodes.caption`` または docutils.nodes.title を探し、これをタイトルとします。

他のキーワード引数はノードのvisitor関数で使われます。詳しくは Sphinx.add_node() を参照して下さい。

バージョン 1.4 で追加.

Sphinx.add_directive(name, func, content, arguments, **options)[ソース]
Sphinx.add_directive(name, directiveclass)

Docutilsのディレクティブを登録します。 name は、ディレクティブ名として今後使っていく名前を設定します。ディレクティブを書く方法には、以下の2通りあります:

  • docutils 0.4スタイル: obj がディレクティブ関数で、 content, arguments および options は関数の属性として設定されます。そして、ディレクティブがコンテンツや引数、オプションを持っているか、それぞれ決定されます。 このスタイルは古いです。

  • docutils 0.5スタイル: has_content, required_arguments, optional_arguments, final_argument_whitespace, option_spec という、必要な属性を初めから持った、 directiveclass という、ディレクティブのためのクラスで定義します。これらの属性は、関数で登録する方法と同じ役割を持っています。詳しくは、 Docutilsの資料 をご覧ください。

    directiveクラスは docutils.parsers.rst.Directive を継承する必要があります。

例えば、 literalinclude というディレクティブを追加する場合には(既に存在していますが)、以下のように書きます:

from docutils.parsers.rst import directives
add_directive('literalinclude', literalinclude_directive,
              content = 0, arguments = (1, 0, 0),
              linenos = directives.flag,
              language = directives.unchanged,
              encoding = directives.encoding)

バージョン 0.6 で変更: Docutils 0.5 スタイルのディレクティブクラスをサポートしました。

Sphinx.add_directive_to_domain(domain, name, func, content, arguments, **options)[ソース]
Sphinx.add_directive_to_domain(domain, name, directiveclass)

add_directive() と似ていますが、ディレクティブを、 domain で指定されたドメインにのみ追加します。

バージョン 1.0 で追加.

Sphinx.add_role(name, role)[ソース]

Docutilsのロールを登録します。 name はドキュメントのソースに表示されるロール名でなければなりません。 role はロールの関数を指定します。詳しくは Docutilsのドキュメント を参照してください。

Sphinx.add_role_to_domain(domain, name, role)[ソース]

add_role() に似ていますが、 domain で指定されたドメインに、新しいロールを追加します。

バージョン 1.0 で追加.

Sphinx.add_generic_role(name, nodeclass)[ソース]

Docutilsのロールを登録します。このロールは特に何もしませんが、与えられた nodeclass を使ってラップされるようになります。

バージョン 0.6 で追加.

Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])[ソース]

このメソッドは、クロスリファレンスを作成できる、新しい object 型を追加できる便利なメソッドです。このメソッドは以下のことを行います:

  • 新しいオブジェクトのための、 directivename で指定された名前を持つ、新しいディレクティブを作成します。もしも indextemplate が空でなければ、自動的に索引のエントリーに追加されます。指定されるばあいには、 %s が一つだけ含まれていなければなりません。このテンプレートがどのように解釈されるかについては、この後のサンプルを参照してください。

  • rolename で指定された名前を持つ、新しいロールが作成されます。これを使用すると、これらのオブジェクトの説明に対して、クロスリファレンスを張ることができるようになります。

  • parse_node を指定する場合には、文字列と、docutilsのノードを受け取る関数を指定しなければなりません。ノードは、その文字列をパースして得られた子供のノードを受け取ります。この関数はクロスリファレンスと索引のエントリーで使用される名前を返さなければなりません。ここの説明のサンプルを見たい場合には、Sphinxのソースコードの conf.py を参照してください。

  • objname (もし与えられなければ、デフォルトでは directivename と同値になります)は、オブジェクトのタイプ名の名前を付けます。これは、検索結果など、オブジェクトを一覧表示する場合に使用されます。

以下のような関数呼び出しが、カスタムのSphinx拡張の中で行われたとすると:

app.add_object_type('directive', 'dir', 'pair: %s; directive')

ドキュメント内で次のようなマークアップが使用できるようになります:

.. rst:directive:: function

   Document a function.

<...>

See also the :rst:dir:`function` directive.

また、このディレクティブを使用すると、以下のようにindexディレクティブを書いたのと同じ索引が作成されます:

.. index:: pair: function; directive

リファレンスノードのクラスは、 ref_nodeclass を指定しない場合には literal (コードの記述に適したプロポーショナルフォントでレンダリングされる)になります。クラスは、docutilsのノードクラスを設定する必要があります。docutilsのクラスの中で頻繁に使用されるのは docutils.nodes.emphasis あるいは docutils.nodes.strong です。もしも装飾が不要であれば、 docutils.nodes.generated も使用できます。もしテキストをリテラルとして処理したいなら(例えばスマートクォート置換が扶養であれば)、そしてタイプライタースタイルで表示したくないなら、 sphinx.addnodes.literal_emphasissphinx.addnodes.literal_strong を使用してください。

ロールの中身に関しては、標準のSphinxのロールと同じ構文を使用できます(クロスリファレンス文法 参照)。

このメソッドは旧名の add_description_unit という名前でも呼び出すことができます。

Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='')[ソース]

このメソッドは ディレクティブの出力が必ず空になることを除けば、 add_object_type() と非常に良く似ています。

これは、セマンティックのターゲットをソースに追加して、カスタムのロールを使用して参照できる(ただし ref のような一般的なものを除く)ということを意味しています。サンプル:

app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)

使用例:

.. topic:: application API

The application API
-------------------

<...>

See also :topic:`this section <application API>`.

もちろん、 topic ディレクティブに続く要素はセクションでなくてもかまいません。

Sphinx.add_transform(transform)[ソース]

標準のDocutilsの Transform のサブクラスの transform をtransformのリストに追加します。これはSphinxがreST形式のドキュメントをパースした後に適用されます。

Sphinx.add_javascript(filename)[ソース]

JavaScriptのファイルのリストに、指定された filename のファイルを追加します。ここで指定されたファイルは、デフォルトのHTMLテンプレートの中にインクルードされます。ファイル名はHTMLの静的パスへの相対パスでなければなりません。詳しくは 設定値のドキュメント を参照してください。 http://example.org/foo.js といった完全なURIのスキームもサポートされています。

バージョン 0.5 で追加.

Sphinx.add_stylesheet(filename)[ソース]

CSSのファイルのリストに、指定された filename のファイルを追加します。ここで指定されたファイルは、デフォルトのHTMLテンプレートの中にインクルードされます。 add_javascript() と同様に、ファイル名はHTMLの静的パスへの相対パスか完全なURIのスキームでなければなりません。

バージョン 1.0 で追加.

Sphinx.add_latex_package(packagename, options=None)[ソース]

LaTeXのソースコードにインクルードするパッケージのリストに packagename を追加します。もし options を与えると、usepackage 宣言のオプション引数として使用します。

app.add_latex_package('mypackage')             # => \usepackage{mypackage}
app.add_latex_package('mypackage', 'foo,bar')  # => \usepackage[foo,bar]{mypackage}

バージョン 1.3 で追加.

Sphinx.add_lexer(alias, lexer)[ソース]

alias で指定された言語で書かれたコードブロックのハイライトを行う、Pygmentsのレキサークラスのインスタンス lexer を設定します。

バージョン 0.6 で追加.

Sphinx.add_autodocumenter(cls)[ソース]

sphinx.ext.autodoc 拡張のための新しいドキュメンタークラスとして、 cls クラスを追加します。この引数は sphinx.ext.autodoc.Documenter のサブクラスでなければなりません。これによって、新しいタイプのオブジェクトの自動ドキュメントが可能になります。どのように Documenter のサブクラスを作ればいいのか、というサンプルを参照したい場合には、autodocモジュールのソースコードを参照してください。

バージョン 0.6 で追加.

Sphinx.add_autodoc_attrgetter(type, getter)[ソース]

組み込みの getattr() 関数と互換性のあるインタフェースを持つ、 getter 関数を追加します。これは type 型のインスタンスのオブジェクトから、自動的に属性を取得してドキュメントを作成するのに使用されます。autodocが型の属性を取得する必要がある場面では、標準の getattr() 関数の代わりに、ここで指定された関数が呼ばれます。

バージョン 0.6 で追加.

Sphinx.add_search_language(cls)[ソース]

言語ごとに、HTMLの全文検索インデックスを構築する、 sphinx.search.SearchLanguage クラスのサブクラスである cls を追加します。このクラスにはどの言語から使われるのかを表す、 lang 属性を持たせる必要があります。詳しくは、 html_search_language を参照してください。

バージョン 1.1 で追加.

Sphinx.add_source_parser(suffix, parser)[ソース]

指定された suffix に対するパーサークラスを登録します。

バージョン 1.4 で追加.

Sphinx.require_sphinx(version)[ソース]

version ('1.1' のような、 メジャー.マイナー 形式のバージョン文字列)と、実行しているSphinxのバージョンを比較して、古すぎる場合にはビルドを中断します。

バージョン 1.0 で追加.

Sphinx.connect(event, callback)[ソース]

event が発行されたときに呼ばれる、 callback を登録します。利用可能なコアイベントと、コールバック関数の引数の詳細情報に関しては Sphinxコアイベント を参照してください。

このメソッドは “リスナーID” を返します。これは disconnect() を呼んで削除する場合の引き数に使用します。

Sphinx.disconnect(listener_id)[ソース]

listener_id で指定されたコールバックの登録を解除します。

exception sphinx.application.ExtensionError[ソース]

ここで説明したすべてのメソッドは、もし拡張APIの中で何か想定外のことが発生した時には、この例外を投げます。

イベントの発行

Sphinx.emit(event, *arguments)[ソース]

event を発行します。コールバック関数には arguments が渡されます。返り値は、すべてのコールバックの返り値がリストに格納されて返されます。拡張機能の中からは、Sphinxのコアのイベントを発行しないでください。

Sphinx.emit_firstresult(event, *arguments)[ソース]

event を発行します。コールバック関数には arguments が渡されます。最初に None 以外を返したコールバックの返り値を返します。

バージョン 0.5 で追加.

メッセージ・ログの生成

アプリケーションオブジェクトは、各種レベルのメッセージ・ログを発行する機能ももちます。

注釈

Sphinxには “error”という関数呼び出しはありません。”error”はビルドを中断させるべきものであり、それをするには例外(sphinx.errors.SphinxErrorやそれを継承したカスタムの例外)を発生させるだけでよいからです。

Sphinx.warn(message, location=None, prefix='WARNING: ', type=None, subtype=None, colorfunc=<function inner>)[ソース]

警告を発生させます。

locationを指定する際は、(docname, lineno)のタプルもしくは、警告の発生場所を詳細に表すような文字列を指定して下さい。

prefix は通常変更するべきではありません。

typesubtypesuppress_warnings でワーニングをサポートするために利用されています。

注釈

パースの最中に生じた警告については、警告をすべて集積し、あとでまとめて出力するため、BuildEnvironment.warn() を使用すべきです

Sphinx.info(message='', nonl=False)[ソース]

種々の情報を出力します。

nonl が真の場合、メッセージの末尾に改行記号を出力しません(つまり、後続のメッセージが続けて出力されることになります)。

Sphinx.verbose(message, *args, **kwargs)[ソース]

冗長な情報を出力します。

このメッセージは冗長性のレベルが1以上(少なくとも1つの -v オプションが与えられる)の場合に出力されます。

メッセージには%形式でのプレイスホルダーを配置することができます。これらは、出力時に *args または **kwargs 引数でフォーマットされます。

Sphinx.debug(message, *args, **kwargs)[ソース]

デバッグ情報を出力します。

このメッセージは冗長性のレベルが2以上(少なくとも2つの -v オプションが与えられる)の場合に出力されます。

メッセージには%形式でのプレイスホルダーを配置することができます。これらは、出力時に *args または **kwargs 引数でフォーマットされます。

Sphinx.debug2(message, *args, **kwargs)[ソース]

低レベルデバッグ情報を出力します。

このメッセージは冗長性のレベルが3(3つの -v オプションが与えられる)の場合に出力されます。

メッセージには%形式でのプレイスホルダーを配置することができます。これらは、出力時に *args または **kwargs 引数でフォーマットされます。

Sphinxコアイベント

Sphinxコアはこれらのイベントを理解します。イベント名に続いて示される引数は、登録されるイベントハンドラに渡されるものです。拡張プログラムの setup 関数 ( 注 conf.py 中でも ``setup 関数を記述すことができます) 内にて メソッドを使用することで、イベントをイベントハンドラーと関連付けます。例えば:

def source_read_handler(app, docname, source):
    print('do something here...')

def setup(app):
    app.connect('source-read', source_read_handler)
builder-inited(app)

ビルダーオブジェクトが作成された時に発行されます。ビルダーオブジェクトは app.builder とすることで参照できます。

env-get-outdated(app, env, added, changed, removed)

ソースファイルが変更されたりして、再読み込みする必要がある場合に発行されます。 added, changed, removed には、ドキュメント名のセットです。さらに追加で読み込み直すべきドキュメントのリストを返すことができます。

バージョン 1.1 で追加.

env-purge-doc(app, env, docname)

ソースファイルが削除されたり、新たに読み込まる場合など、環境の中に含まれるソースファイルの関連情報をクリアすべき状況になった場合に発行されます。環境の属性の中に情報をキャッシュしておくような拡張機能ためのイベントです。

例えば、環境の中にすべてのモジュールのキャッシュが存在してる場合、ソースファイルが変更されると、ファイルからモジュール宣言から削除されてから、そのファイルに関するキャッシュのエントリーはクリアされます。

バージョン 0.5 で追加.

env-before-read-docs(app, env, docnames)

環境がすべての追加および変更されたファイルのリストを決定し、そのリストを読み込む直前に発行されるイベントです。拡張機能の作者は処理の直前にドキュメント名リストの順序を(インプレイスで)変更したり、Sphinxが変更を把握出来なかったドキュメント名を追加(ただし env.found_doc にないドキュメント名は決して追加しないでください)することができます。

イベントハンドラはドキュメント名をリストから削除することもできます; 注意深くこの方法を利用することで、Sphinxに変更済みのファイルを未変更であるとして扱わせることができます。

バージョン 1.3 で追加.

source-read(app, docname, source)

ソースファイルが読み込まれる時に発行されます。 source 引数はリストで、ひとつの要素はソースファイルのコンテンツを表します。コンテンツに関する処理を行ったり、要素に関してソースレベルでの変換を実装したりできます。

もしも、LaTeXと同じように、 $ 記号を、インラインの数式の区切り文字にしたい場合には、このイベントハンドラの中で、正規表現を使用して $...$:math:`...` に置き換えることで実現できます。

バージョン 0.5 で追加.

doctree-read(app, doctree)

doctreeがパースされ、環境から読み込まれ、pickle化される時に発行されます。 doctree をその場で変更できます。

missing-reference(app, env, node, contnode)

Pythonモジュールやオブジェクトへの相互参照が解決できないときに発行されます。もしも参照の問題を解決できる場合には、 node の代わりにドキュメントツリーに挿入される、新しいdocutilsのノードを返すことで、イベントハンドラ側で解決できます。通常このノードは、 contnode を子供として含む reference ノードです。

パラメータ:
  • env – ビルド環境 (app.builder.env)
  • node – これから解決される pending_xref ノード。この属性は reftypereftargetmodnameclassname 属性であり、これらの属性によって、型と参照先ターゲットが決定されます。
  • contnode – このノードは、将来の参照が持つ、テキストとフォーマット情報を持ちます。これは返される参照ノードの子供にならなければなりません。

バージョン 0.5 で追加.

doctree-resolved(app, doctree, docname)

環境がdoctreeに関して”resolved(解決)”と判断したときに発行されます。これは、すべての参照が解決され、目次が挿入された時、ということになります。 doctree はこのイベントハンドラ内で操作できます。

このイベントは、ライタークラスにビジターメソッドが存在しない、カスタムのノードを置換して処理するのに使用できます。もしもここで設定しない場合、未知のノードを見つけると、ライターはエラーを出しますが、設定することでエラーが出なくなります。

env-merge-info(env, docnames, other)

このイベントはドキュメントの並列読み込みが有効の場合にのみ発行されます。それぞれのサブプロセスがドキュメントを読み込んだ場合に一度だけ発行されます。

このイベントは拡張機能が特定の場所の環境中にデータを保存する場合に使用される必要があります。使用しないと、サブプロセス中で保存された情報をメインプロセスの環境内で利用できなくなります。

other はサブプロセス中での環境、env はメインプロセスでの環境です。docnames はこのサブプロセスにおいて読み込まれたドキュメント名のセットです。

このイベントの使用例については、 標準で提供されている sphinx.ext.todo を参照してください。この実装方法は env-purge-doc に似ています、ただし、情報が削除されるだけではなく、他の環境からの情報をメインプロセス環境に追加することができます。

バージョン 1.3 で追加.

env-updated(app, env)

ビルダーの update() メソッドの実行が完了し、環境とすべてのdoctreeが最新になった時に発行されます。

イベントハンドラより、ドキュメント名のイテレータを返すことができます。これらのドキュメントはアップデートされたとみなされ、書き込みフェイズにて新規書き込み(または書き換え)が行われます。

バージョン 0.5 で追加.

バージョン 1.3 で変更: イベントハンドラからの戻り値が利用されるようになりました。

html-collect-pages(app)

HTMLビルダーが、ドキュメント以外のページの書き込みを開始するときに発行されます。 (pagename, context, templatename) という構成の要素を含むシーケンスを返すと、ページを追加できます。

バージョン 1.0 で追加.

html-page-context(app, pagename, templatename, context, doctree)

HTMLビルダーがコンテキストの辞書を作り、テンプレートを使用してレンダリングを行う時に発行されます。このイベントは、追加のカスタムの要素をコンテキストに追加する場合に使用できます。

pagename 引数はレンダリングされるページの、規範に則った名前です。規範というのは、 .html が付かず、パス区切りとしてスラッシュ(/)が使われている状態です。 templatename はレンダリングに使用するテンプレートの名前です。 reSTドキュメントのページのレンダリング時には、必ず 'page.html' となります。

context 引数はテンプレートエンジンがページをレンダリングする際に与えられる値の辞書になります。カスタムの値を持つように、変更することが可能です。キーは必ず文字列です。

doctree 引数はreSTドキュメントから作成する場合にはdoctreeとなります。もしもHTMLテンプレートからのみ作成されるページの場合には、 None となります。

イベントハンドラは文字列を返すことができます、この文字列は 'page.html' に代わりHTMLテンプレートとして、このページのレンダリングに利用されるテンプレート名になります。

バージョン 0.4 で追加.

バージョン 1.3 で変更: 戻り値により使用するテンプレート名を指定できるようになりました。

build-finished(app, exception)

ビルドが完了し、Sphinxが終了する際に発行されます。通常はクリーンアップに使用されます。このイベントは、ビルドプロセスが例外を上げたときにも発行されます。その場合には、 exception 引数が渡されます。アプリケーションの中で発生した例外は、このイベントハンドラが終了した段階で、再度投げられます。もしもビルドプロセスが例外を発生しなかった場合には、 exceptionNone になります。これによって、例外の種類ごとの、クリーンアップの処理をカスタム化できます。

バージョン 0.5 で追加.

Sphinx のバージョン確認

作製した拡張をSphinxのAPI変更に追従させる為、この仕組みを使用してください。

sphinx.version_info

5つの要素を持ったタプルです; Sphinx のバージョンが 1.2.1 beta 3 の場合、(1, 2, 1, 'beta', 3) となります。

バージョン 1.2 で追加: 1.2より前のバージョンでは sphinx.__version__ の文字列により確認してください。

Config オブジェクト

class sphinx.config.Config[ソース]

config オブジェクトはすべての設定値を属性として利用できるよう保持します。

これは、アプリケーションおよび環境オブジェクト内において、 config 属性としてアクセスできます。例えば、 language の値を取得したい場合、app.config.language または env.config.language のように使用します。

テンプレートブリッジ

class sphinx.application.TemplateBridge[ソース]

このクラスは、”テンプレートへのブリッジ”を定義しています。テンプレートブリッジというのは、与えられたテンプレート名と、コンテキストを利用して、テンプレートをレンダリングするクラスのことです。

init(builder, theme=None, dirs=None)[ソース]

テンプレートのシステムの初期化を行うために、ビルダーから呼ばれます。

builder はビルダーオブジェクトで、 builder.config.templates_path の値を使用することになるでしょう。

themesphinx.theming.Theme オブジェクト、あるいは None になります。後者の場合には、 dirs に固定ディレクトリのパスが入ったリストが渡され、この中からテンプレートを探します。

newest_template_mtime()[ソース]

このメソッドはビルダーから呼ばれます。テンプレートが変更されたことで、出力ファイルを再レンダリングする必要があるかどうかの判断をするために使用されます。変更された、最新のテンプレートのmtimeを返します。デフォルトの実装では 0 を返します。

render(template, context)[ソース]

指定された context (Python辞書)を使用して、 template で指定されたファイル名のテンプレートのレンダリングを行います。ビルダーから呼ばれます。

render_string(template, context)[ソース]

指定された context (Python辞書)を使用して、 template で指定された文字列形式のテンプレートのレンダリングを行います。ビルダーから呼ばれます。

例外

exception sphinx.errors.SphinxError[ソース]

これは “ナイスな” 例外を作成するための基底クラスです。この例外が発生すると、Sphinxはビルドを中止し、例外のカテゴリとメッセージをユーザーに表示します。

拡張プログラムでは、この例外を継承しカスタマイズすることが強く推奨されます。

SphinxError から 継承されない 例外は予期しない例外として扱われ、トレースバックの一部を表示(そして、全部を一時ファイルに保存)します。

category

例外の “category” の記述部分は、例外内容を文字列に変換する場合に利用されます(“category: message” という書式)。 例外のサブクラスに応じて適切に設定するべきです。

exception sphinx.errors.ConfigError[ソース]

コンフィグ値において、誤った値や、おかしな値の組み合わせが与えられた場合に利用されます。

exception sphinx.errors.ExtensionError[ソース]

拡張機能のセットアップ中に発生した例外に対して使用します。

exception sphinx.errors.ThemeError[ソース]

テーマの処理中に生じた例外に対して使用します。

exception sphinx.errors.VersionRequirementError[ソース]

ドキュメントが現在よりも高いSphinxのバージョンを要求した場合に発生します。