アプリケーション API

各 Sphinx 拡張機能は、少なくとも setup() 関数を持つ Python モジュールです。この関数は初期化時に、Sphinx プロセスを表すアプリケーションオブジェクトを引数として呼び出されます。

class sphinx.application.Sphinx

このアプリケーションオブジェクトは、以下に説明する公開 API を持っています。

拡張機能の設定

これらのメソッドは通常、拡張機能の setup() 関数内で呼び出されます。

Sphinx 拡張機能 API の使用例は、sphinx.ext パッケージで見ることができます。

Sphinx.setup_extension(extname: str) → None

Sphinx 拡張モジュールをインポートして設定します。

モジュール *name* で指定された拡張機能をロードします。拡張機能が別の拡張機能によって提供される機能を必要とする場合は、これを使用します。2 回呼び出された場合は、ノーオペレーションです。

static Sphinx.require_sphinx(version: tuple[int, int] | str) → None

要求された場合は、Sphinx のバージョンを確認します。

実行中の Sphinx のバージョンと *version* を比較し、古すぎる場合はビルドを中止します。

パラメータ:

version -- 必須バージョンを major.minor または (major, minor) の形式で指定します。

バージョン 1.0 で追加。

バージョン 7.1 で変更: *version* の型で、(major, minor) 形式が許可されるようになりました。

Sphinx.connect(event: Literal['config-inited'], callback: Callable[[Sphinx, Config], None], priority: int = 500) → int

Sphinx.connect(event: Literal['builder-inited'], callback: Callable[[Sphinx], None], priority: int = 500) → int

Sphinx.connect(event: Literal['env-get-outdated'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], Set[str], Set[str]], Sequence[str]], priority: int = 500) → int

Sphinx.connect(event: Literal['env-before-read-docs'], callback: Callable[[Sphinx, BuildEnvironment, list[str]], None], priority: int = 500) → int

Sphinx.connect(event: Literal['env-purge-doc'], callback: Callable[[Sphinx, BuildEnvironment, str], None], priority: int = 500) → int

Sphinx.connect(event: Literal['source-read'], callback: Callable[[Sphinx, str, list[str]], None], priority: int = 500) → int

Sphinx.connect(event: Literal['include-read'], callback: Callable[[Sphinx, Path, str, list[str]], None], priority: int = 500) → int

Sphinx.connect(event: Literal['doctree-read'], callback: Callable[[Sphinx, nodes.document], None], priority: int = 500) → int

Sphinx.connect(event: Literal['env-merge-info'], callback: Callable[[Sphinx, BuildEnvironment, list[str], BuildEnvironment], None], priority: int = 500) → int

Sphinx.connect(event: Literal['env-updated'], callback: Callable[[Sphinx, BuildEnvironment], str], priority: int = 500) → int

Sphinx.connect(event: Literal['env-get-updated'], callback: Callable[[Sphinx, BuildEnvironment], Iterable[str]], priority: int = 500) → int

Sphinx.connect(event: Literal['env-check-consistency'], callback: Callable[[Sphinx, BuildEnvironment], None], priority: int = 500) → int

Sphinx.connect(event: Literal['write-started'], callback: Callable[[Sphinx, Builder], None], priority: int = 500) → int

Sphinx.connect(event: Literal['doctree-resolved'], callback: Callable[[Sphinx, nodes.document, str], None], priority: int = 500) → int

Sphinx.connect(event: Literal['missing-reference'], callback: Callable[[Sphinx, BuildEnvironment, addnodes.pending_xref, nodes.TextElement], nodes.reference | None], priority: int = 500) → int

Sphinx.connect(event: Literal['warn-missing-reference'], callback: Callable[[Sphinx, Domain, addnodes.pending_xref], bool | None], priority: int = 500) → int

Sphinx.connect(event: Literal['build-finished'], callback: Callable[[Sphinx, Exception | None], None], priority: int = 500) → int

Sphinx.connect(event: Literal['html-collect-pages'], callback: Callable[[Sphinx], Iterable[tuple[str, dict[str, Any], str]]], priority: int = 500) → int

Sphinx.connect(event: Literal['html-page-context'], callback: Callable[[Sphinx, str, str, dict[str, Any], nodes.document], str | None], priority: int = 500) → int

Sphinx.connect(event: Literal['linkcheck-process-uri'], callback: Callable[[Sphinx, str], str | None], priority: int = 500) → int

Sphinx.connect(event: Literal['object-description-transform'], callback: Callable[[Sphinx, str, str, addnodes.desc_content], None], priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-process-docstring'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, dict[str, bool], Sequence[str]], None], priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-before-process-signature'], callback: Callable[[Sphinx, Any, bool], None], priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-process-signature'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, dict[str, bool], str | None, str | None], tuple[str | None,

Sphinx.connect(event: Literal['autodoc-process-bases'], callback: Callable[[Sphinx, str, Any, dict[str, bool], list[str]], None], priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-skip-member'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, bool, dict[str, bool]], bool], priority: int = 500) → int

Sphinx.connect(event: Literal['todo-defined'], callback: Callable[[Sphinx, todo_node], None], priority: int = 500) → int

Sphinx.connect(event: Literal['viewcode-find-source'], callback: Callable[[Sphinx, str], tuple[str, dict[str, tuple[Literal['class', 'def', 'other'], int, int]]]], priority: int = 500) → int

Sphinx.connect(event: Literal['viewcode-follow-imported'], callback: Callable[[Sphinx, str, str], str | None], priority: int = 500) → int

Sphinx.connect(event: str, callback: Callable[..., Any], priority: int = 500) → int

event が発生したときに呼び出される callback を登録します。

利用可能なコアイベントとコールバック関数の引数の詳細については、イベントコールバック APIを参照してください。

パラメータ:

• event – 対象イベントの名前

• callback – イベントのコールバック関数

• priority – コールバックの優先度。コールバックは、priority の順（昇順）に呼び出されます。

戻り値:

リスナーID。これは、disconnect() で使用できます。

バージョン 3.0 で変更: priority のサポート

Sphinx.disconnect(listener_id: int) → None

listener_id でコールバックの登録を解除します。

パラメータ:

listener_id – connect() が返す listener_id

Sphinx.add_builder(builder: type[Builder], override: bool = False) → None

新しいビルダーを登録します。

パラメータ:

• builder – ビルダーのクラス

• override – trueの場合、同じ名前で別のビルダーが既にインストールされている場合でも、強制的にビルダーをインストールします。

バージョン 1.8 で変更: override キーワードを追加。

Sphinx.add_config_value(name: str, default: Any, rebuild: _ConfigRebuild, types: type | Collection[type] | ENUM = (), description: str = '') → None

設定値を登録します。

これは、Sphinxが新しい値を認識し、それに応じてデフォルト値を設定するために必要です。

パラメータ:

• name – 設定値の名前。拡張機能名でプレフィックスを付けることを推奨します (例: html_logo、 epub_title)

• default – 設定値のデフォルト値。

• rebuild –

  再構築の条件。次のいずれかの値でなければなりません。

  • 設定の変更がドキュメントの解析時にのみ有効になる場合は 'env'。これは、環境全体を再構築する必要があることを意味します。

  • 設定の変更でHTMLドキュメントの完全な再構築が必要な場合は 'html'。

  • 設定の変更で特別な再構築が必要ない場合は ''。

• types – 設定値の型。型のリストを指定できます。たとえば、[str] は、文字列値を取る設定を記述するために使用されます。

• description – 設定値の簡単な説明。

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

バージョン 0.6 で変更: rebuild を単純なブール値（'' または 'env' に相当）から文字列に変更。ただし、ブール値は引き続き受け入れられ、内部的に変換されます。

バージョン 7.4 で追加: description パラメータ。

Sphinx.add_event(name: str) → None

name というイベントを登録します。

これは、イベントを発行できるようにするために必要です。

パラメータ:

name – イベントの名前

Sphinx.set_translator(name: str, translator_class: type[nodes.NodeVisitor], override: bool = False) → None

Docutilsトランスレータクラスを登録またはオーバーライドします。

これは、カスタム出力トランスレータを登録したり、組み込みトランスレータを置き換えたりするために使用されます。これにより、拡張機能はカスタムトランスレータを使用し、トランスレータ用のカスタムノードを定義できます（add_node()を参照）。

パラメータ:

• name – トランスレータのビルダーの名前

• translator_class – トランスレータクラス

• override – trueの場合、同じ名前で別のトランスレータが既にインストールされている場合でも、強制的にトランスレータをインストールします。

バージョン 1.3 で追加。

バージョン 1.8 で変更: override キーワードを追加。

Sphinx.add_node(node: type[Element], override: bool = False, **kwargs: tuple[Callable, Callable | None]) → None

Docutilsノードクラスを登録します。

これは、Docutilsの内部処理に必要です。また、解析されたドキュメント内のノードを検証するために将来使用される可能性があります。

パラメータ:

• node – ノードクラス

• kwargs – 各ビルダーのビジター関数（下記参照）

• override – trueの場合、同じ名前で別のノードが既にインストールされている場合でも、強制的にノードをインストールします。

SphinxのHTML、LaTeX、テキスト、およびmanpageライターのノードビジター関数は、キーワード引数として与えることができます。キーワードは、'html'、'latex'、'text'、'man'、'texinfo'、またはその他のサポートされているトランスレーターのいずれか1つ以上である必要があり、値は(visit, depart)メソッドの2タプルである必要があります。visit関数がdocutils.nodes.SkipNodeを発生させる場合、departはNoneにすることができます。例

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: type[Element], figtype: str, title_getter: TitleGetter | None = None, override: bool = False, **kwargs: tuple[Callable, Callable]) → None

Docutilsノードクラスを番号付き対象として登録します。

Sphinxはノードに自動的に番号を付けます。その後、ユーザーはnumrefを使用してそれを参照できます。

パラメータ:

• node – ノードクラス

• figtype – 番号付け可能なノードのタイプ。各figtypeには個別の番号付けシーケンスがあります。システムfigtypeとして、figure、table、code-blockが定義されています。これらのデフォルトのfigtypeにカスタムノードを追加できます。新しいfigtypeが指定された場合、新しいカスタムfigtypeを定義することも可能です。

• title_getter – ノードのタイトルを取得するためのゲッター関数。番号付け可能なノードのインスタンスを受け取り、そのタイトルを文字列として返す必要があります。タイトルは、refへの参照のデフォルトタイトルとして使用されます。デフォルトでは、Sphinxはノードからdocutils.nodes.captionまたはdocutils.nodes.titleをタイトルとして検索します。

• kwargs – 各ビルダーのビジター関数(add_node()と同じ)

• override – trueの場合、同じ名前で別のノードが既にインストールされている場合でも、強制的にノードをインストールします。

バージョン 1.4 で追加。

Sphinx.add_directive(name: str, cls: type[Directive], override: bool = False) → None

Docutilsディレクティブを登録します。

パラメータ:

• name – ディレクティブの名前

• cls – ディレクティブクラス

• override – falseの場合、同じ名前で別のディレクティブがすでにインストールされている場合はインストールしないでください。trueの場合、無条件にディレクティブをインストールします。

たとえば、my-directiveという名前のカスタムディレクティブは、次のように追加されます

from docutils.parsers.rst import Directive, directives

class MyDirective(Directive):
    has_content = True
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = True
    option_spec = {
        'class': directives.class_option,
        'name': directives.unchanged,
    }

    def run(self):
        ...

def setup(app):
    app.add_directive('my-directive', MyDirective)

詳細については、Docutilsのドキュメントを参照してください。

バージョン 0.6 で変更: Docutils 0.5スタイルのディレクティブクラスがサポートされるようになりました。

バージョン 1.8 から非推奨: Docutils 0.4 スタイル (関数ベース) のディレクティブのサポートは非推奨です。

バージョン 1.8 で変更: override キーワードを追加。

Sphinx.add_role(name: str, role: Any, override: bool = False) → None

Docutilsロールを登録します。

パラメータ:

• name – ロールの名前

• role – ロール関数

• override – falseの場合、同じ名前で別のロールがすでにインストールされている場合はインストールしないでください。trueの場合、無条件にロールをインストールします。

ロール関数の詳細については、Docutilsのドキュメントを参照してください。

バージョン 1.8 で変更: override キーワードを追加。

Sphinx.add_generic_role(name: str, nodeclass: type[Node], override: bool = False) → None

汎用Docutilsロールを登録します。

nodeclassで指定されたノードに内容をラップする以外は何もしないDocutilsロールを登録します。

パラメータ:

override – falseの場合、同じ名前で別のロールがすでにインストールされている場合はインストールしないでください。trueの場合、無条件にロールをインストールします。

バージョン 0.6 で追加。

バージョン 1.8 で変更: override キーワードを追加。

Sphinx.add_domain(domain: type[Domain], override: bool = False) → None

ドメインを登録します。

パラメータ:

• domain – ドメインクラス

• override – falseの場合、同じ名前で別のドメインが既にインストールされている場合はインストールしません。trueの場合、無条件にドメインをインストールします。

バージョン 1.0 で追加。

バージョン 1.8 で変更: override キーワードを追加。

Sphinx.add_directive_to_domain(domain: str, name: str, cls: type[Directive], override: bool = False) → None

ドメインにDocutilsディレクティブを登録します。

add_directive()と同様ですが、ディレクティブはdomainという名前のドメインに追加されます。

パラメータ:

• domain – 対象ドメインの名前

• name – ディレクティブの名前

• cls – ディレクティブクラス

• override – falseの場合、同じ名前で別のディレクティブがすでにインストールされている場合はインストールしないでください。trueの場合、無条件にディレクティブをインストールします。

バージョン 1.0 で追加。

バージョン 1.8 で変更: override キーワードを追加。

Sphinx.add_role_to_domain(domain: str, name: str, role: RoleFunction | XRefRole, override: bool = False) → None

ドメインにDocutilsロールを登録します。

add_role()と同様ですが、ロールはdomainという名前のドメインに追加されます。

パラメータ:

• domain – 対象ドメインの名前

• name – ロールの名前

• role – ロール関数

• override – falseの場合、同じ名前で別のロールがすでにインストールされている場合はインストールしないでください。trueの場合、無条件にロールをインストールします。

バージョン 1.0 で追加。

バージョン 1.8 で変更: override キーワードを追加。

Sphinx.add_index_to_domain(domain: str, index: type[Index], _override: bool = False) → None

ドメインのカスタムインデックスを登録します。

カスタムのindexクラスを、domainという名前のドメインに追加します。

パラメータ:

• domain – 対象ドメインの名前

• index – インデックスクラス

• override – falseの場合、同じ名前で別のインデックスが既にインストールされている場合はインストールしません。trueの場合、無条件にインデックスをインストールします。

バージョン 1.0 で追加。

バージョン 1.8 で変更: override キーワードを追加。

Sphinx.add_object_type(directivename: str, rolename: str, indextemplate: str = '', parse_node: Callable | None = None, ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', doc_field_types: Sequence = (), override: bool = False) → None

新しいオブジェクトタイプを登録します。

このメソッドは、相互参照可能な新しいオブジェクトタイプを追加する非常に便利な方法です。これは次のことを行います。

• オブジェクトをドキュメント化するための新しいディレクティブ（directivenameと呼ばれる）を作成します。indextemplateが空でない場合、インデックスエントリが自動的に追加されます。指定する場合は、%sのインスタンスを1つだけ含める必要があります。テンプレートの解釈方法については、以下の例を参照してください。

• これらのオブジェクト記述への相互参照のための新しいロール（rolenameと呼ばれる）を作成します。

• parse_nodeを指定する場合、文字列とdocutilsノードを受け取る関数である必要があり、文字列から解析された子を持つノードを設定する必要があります。次に、相互参照およびインデックスエントリで使用する項目の名前を返す必要があります。このドキュメントのソースにある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:: pair: function; directive

参照ノードは、ref_nodeclass 引数が指定されない限り、literal クラス（コードに適したプロポーショナルフォントでレンダリングされます）になります。ref_nodeclass 引数には、docutils のノードクラスを指定する必要があります。最も有用なのは、docutils.nodes.emphasis または docutils.nodes.strong です。さらにテキスト装飾をしない場合は、docutils.nodes.generated を使用することもできます。テキストをリテラルとして扱うべき（例：スマートクォートの置換をしない）が、タイプライターのようなスタイルにはしたくない場合は、sphinx.addnodes.literal_emphasis または sphinx.addnodes.literal_strong を使用してください。

ロールの内容については、標準の Sphinx ロールと同様の構文を使用できます（相互参照の構文を参照してください）。

override が True の場合、指定された object_type は、同じ名前の object_type が既にインストールされている場合でも強制的にインストールされます。

バージョン 1.8 で変更: override キーワードを追加。

Sphinx.add_crossref_type(directivename: str, rolename: str, indextemplate: str = '', ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', override: bool = False) → None

新しい相互参照オブジェクトタイプを登録します。

このメソッドは、add_object_type() と非常によく似ていますが、生成するディレクティブは空でなければならず、出力も生成しません。

つまり、ソースにセマンティックターゲットを追加し、汎用的なロール（ref など）の代わりにカスタムロールを使用してそれらを参照できるということです。呼び出しの例：

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

使用例：

.. topic:: application API

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

Some random text here.

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

（もちろん、topic ディレクティブの後に続く要素はセクションである必要はありません。）

パラメータ:

override – false の場合、同じ名前で別の相互参照タイプが既にインストールされている場合はインストールしません。true の場合、無条件に相互参照タイプをインストールします。

バージョン 1.8 で変更: override キーワードを追加。

Sphinx.add_transform(transform: type[Transform]) → None

解析後に適用される Docutils トランスフォームを登録します。

標準の docutils Transform サブクラス transform を、Sphinx が reST ドキュメントを解析した後に適用されるトランスフォームのリストに追加します。

パラメータ:

transform – トランスフォームクラス

Sphinx トランスフォームの優先度範囲カテゴリ

優先度	Sphinx の主な目的
0-99	docutils による無効なノードの修正。ドキュメントツリーの変換。
100-299	準備
300-399	初期
400-699	メイン
700-799	後処理。テキストと参照を修正するための締め切り。
800-899	参照と参照されているノードの収集。ドメイン処理。
900-999	最終処理とクリーンアップ。

参照: トランスフォーム優先度範囲カテゴリ

Sphinx.add_post_transform(transform: type[Transform]) → None

書き込み前に適用される Docutils トランスフォームを登録します。

標準の docutils Transform サブクラス transform を、Sphinx がドキュメントを書き込む前に適用されるトランスフォームのリストに追加します。

パラメータ:

transform – トランスフォームクラス

Sphinx.add_js_file(filename: str | None, priority: int = 500, loading_method: str | None = None, **kwargs: Any) → None

HTML 出力に含める JavaScript ファイルを登録します。

パラメータ:

• filename – デフォルトの HTML テンプレートに含める JavaScript ファイルの名前。HTML 静的パスからの相対パス、スキーム付きの完全な URI、または None である必要があります。None 値は、インラインの <script> タグを作成するために使用されます。下記の kwargs の説明を参照してください。

• priority – ファイルは優先度の昇順で含まれます。複数の JavaScript ファイルが同じ優先度を持つ場合、それらのファイルは登録順に含まれます。下記の「JavaScript ファイルの優先度範囲」のリストを参照してください。

• loading_method – JavaScript ファイルの読み込み方法。'async' または 'defer' のいずれかが許可されます。

• kwargs – 追加のキーワード引数は、<script> タグの属性として含まれます。特別なキーワード引数 body が指定されている場合、その値は <script> タグの内容として追加されます。

例：

app.add_js_file('example.js')
# => <script src="_static/example.js"></script>

app.add_js_file('example.js', loading_method="async")
# => <script src="_static/example.js" async="async"></script>

app.add_js_file(None, body="var myVariable = 'foo';")
# => <script>var myVariable = 'foo';</script>

JavaScript ファイルの優先度範囲

優先度	Sphinx の主な目的
200	組み込み JavaScript ファイルのデフォルト優先度
500	拡張機能のデフォルト優先度
800	html_js_files のデフォルト優先度

拡張機能が html-page-context イベントでこのメソッドを呼び出すと、特定の HTML ページに JavaScript ファイルを追加できます。

バージョン 0.5 で追加。

バージョン 1.8 で変更: app.add_javascript() から名前が変更されました。また、スクリプトタグの属性としてキーワード引数を許可するようになりました。

バージョン 3.5 で変更: priority 引数を追加。特定のページに JavaScript ファイルを追加できるようになりました。

バージョン 4.4 で変更: loading_method 引数を追加。JavaScript ファイルの読み込み方法を変更できるようになりました。

Sphinx.add_css_file(filename: str, priority: int = 500, **kwargs: Any) → None

HTML 出力に含めるスタイルシートを登録します。

パラメータ:

• filename – デフォルトの HTML テンプレートに含める CSS ファイルの名前。HTML 静的パスからの相対パス、またはスキーム付きの完全な URI である必要があります。

• priority – ファイルは priority の昇順で含まれます。複数の CSS ファイルが同じ priority を持つ場合、それらのファイルは登録された順に含まれます。以下の「CSS ファイルの priority 範囲」のリストを参照してください。

• kwargs – 追加のキーワード引数は、<link> タグの属性として含まれます。

例：

app.add_css_file('custom.css')
# => <link rel="stylesheet" href="_static/custom.css" type="text/css" />

app.add_css_file('print.css', media='print')
# => <link rel="stylesheet" href="_static/print.css"
#          type="text/css" media="print" />

app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
# => <link rel="alternate stylesheet" href="_static/fancy.css"
#          type="text/css" title="fancy" />

CSS ファイルの priority 範囲

優先度	Sphinx の主な目的
200	組み込み CSS ファイルのデフォルト priority
500	拡張機能のデフォルト優先度
800	html_css_files のデフォルト priority

拡張機能が html-page-context イベントでこのメソッドを呼び出すと、特定の HTML ページに CSS ファイルを追加できます。

バージョン 1.0 で追加。

バージョン 1.6 で変更: オプションの alternate および/または title 属性を引数 alternate (ブール値) および title (文字列) で指定できます。デフォルトではタイトルはなく、alternate = False です。詳細については、ドキュメントを参照してください。

バージョン 1.8 で変更: app.add_stylesheet() から名前が変更されました。また、リンクタグの属性としてキーワード引数を使用できるようになりました。

バージョン 3.5 で変更: priority 引数を追加。特定のページに CSS ファイルを追加できるようになりました。

Sphinx.add_latex_package(packagename: str, options: str | None = None, after_hyperref: bool = False) → None

LaTeX ソースコードに含めるパッケージを登録します。

LaTeX ソースコードに含めるパッケージのリストに packagename を追加します。options を指定すると、usepackage 宣言で使用されます。after_hyperref が真の場合、パッケージは hyperref パッケージの後にロードされます。

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

バージョン 1.3 で追加。

バージョン 3.1 で追加: after_hyperref オプション。

Sphinx.add_lexer(alias: str, lexer: type[Lexer]) → None

ソースコード用の新しい字句解析器を登録します。

指定された言語 alias でコードブロックを強調表示するには、lexer を使用します。

バージョン 0.6 で追加。

バージョン 2.1 で変更: 引数として字句解析器クラスを取るようになりました。

バージョン 4.0 で変更: 引数としての字句解析器インスタンスのサポートを削除しました。

Sphinx.add_autodocumenter(cls: type[Documenter], override: bool = False) → None

autodoc 拡張機能用の新しいドキュメンタークラスを登録します。

sphinx.ext.autodoc 拡張機能用の新しいドキュメンタークラスとして cls を追加します。これは sphinx.ext.autodoc.Documenter のサブクラスである必要があります。これにより、新しいタイプのオブジェクトを自動的にドキュメント化できます。Documenter をサブクラス化する方法の例については、autodoc モジュールのソースを参照してください。

override が True の場合、同じ名前を持つドキュメンターがすでにインストールされていても、指定された cls が強制的にインストールされます。

autodoc 拡張機能の開発を参照してください。

バージョン 0.6 で追加。

バージョン 2.2 で変更: override キーワードを追加。

Sphinx.add_autodoc_attrgetter(typ: type, getter: Callable[[Any, str, Any], Any]) → None

autodoc 拡張機能用の新しい getattr 類似の関数を登録します。

typ のインスタンスであるオブジェクトの autodoc 属性ゲッターとして、getattr() 組み込みと互換性のあるインターフェースを持つ関数である getter を追加します。autodoc が型の属性を取得する必要があるすべての場合、getattr() の代わりにこの関数によって処理されます。

バージョン 0.6 で追加。

Sphinx.add_search_language(cls: type[SearchLanguage]) → None

HTML 検索インデックス用の新しい言語を登録します。

sphinx.search.SearchLanguage のサブクラスである必要がある cls を、HTML フルテキスト検索インデックスを構築するためのサポート言語として追加します。クラスには、使用する言語を示す lang 属性が必要です。html_search_language を参照してください。

バージョン 1.1 で追加。

Sphinx.add_source_suffix(suffix: str, filetype: str, override: bool = False) → None

ソースファイルの拡張子を登録します。

source_suffix と同じです。ユーザーは設定でこれをオーバーライドできます。

パラメータ:

override – falseの場合、同じ拡張子が既にインストールされている場合はインストールしません。trueの場合、無条件に拡張子をインストールします。

バージョン1.8で追加。

Sphinx.add_source_parser(parser: type[Parser], override: bool = False) → None

パーサクラスを登録します。

パラメータ:

override – falseの場合、同じ拡張子に対して別のパーサーが既にインストールされている場合はインストールしません。trueの場合、無条件にパーサーをインストールします。

バージョン 1.4 で追加。

バージョン1.8で変更: suffix 引数は非推奨です。parser 引数のみを受け付けます。代わりに拡張子を登録するには、add_source_suffix() API を使用してください。

バージョン 1.8 で変更: override キーワードを追加。

Sphinx.add_env_collector(collector: type[EnvironmentCollector]) → None

環境コレクタークラスを登録します。

環境コレクター API を参照してください。

バージョン1.6で追加。

Sphinx.add_html_theme(name: str, theme_path: str) → None

HTML テーマを登録します。

name はテーマの名前、theme_path はテーマへのフルパスです（参照：Python パッケージとしてテーマを配布する）。

バージョン1.6で追加。

Sphinx.add_html_math_renderer(name: str, inline_renderers: tuple[Callable, Callable | None] | None = None, block_renderers: tuple[Callable, Callable | None] | None = None) → None

HTML 用の数式レンダラーを登録します。

name は数式レンダラーの名前です。inline_renderers と block_renderers は両方とも HTML ライターのビジター関数として使用されます。前者はインライン数式ノード（nodes.math）用、後者はブロック数式ノード（nodes.math_block）用です。ビジター関数については、詳細については add_node() を参照してください。

バージョン1.8で追加。

Sphinx.add_message_catalog(catalog: str, locale_dir: str) → None

メッセージカタログを登録します。

パラメータ:

• catalog – カタログの名前

• locale_dir – メッセージカタログのベースパス

詳細については、sphinx.locale.get_translation() を参照してください。

バージョン1.8で追加。

Sphinx.is_parallel_allowed(typ: str) → bool

並列処理が許可されているかどうかを確認します。

パラメータ:

typ – 処理の種類; 'read' または 'write'。

exception sphinx.application.ExtensionError

これらのメソッドはすべて、拡張 API で問題が発生した場合にこの例外を発生させます。

イベントの発行

class sphinx.application.Sphinx

emit(event: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → list

event を発行し、コールバック関数に arguments を渡します。

すべてのコールバックの戻り値をリストとして返します。拡張機能内でSphinxのコアイベントを発行しないでください！

パラメータ:

• event – 発行されるイベントの名前

• args – イベントの引数

• allowed_exceptions – コールバックで許可される例外のリスト

バージョン 3.1 で変更: スルーパス例外を指定するために allowed_exceptions を追加しました

emit_firstresult(event: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → Any

event を発行し、コールバック関数に arguments を渡します。

Noneを返さない最初のコールバックの結果を返します。

パラメータ:

• event – 発行されるイベントの名前

• args – イベントの引数

• allowed_exceptions – コールバックで許可される例外のリスト

バージョン 0.5 で追加。

バージョン 3.1 で変更: スルーパス例外を指定するために allowed_exceptions を追加しました

Sphinxのランタイム情報

アプリケーションオブジェクトは、属性としてランタイム情報も提供します。

Sphinx.project

ターゲットプロジェクト。Projectを参照してください。

Sphinx.srcdir

ソースディレクトリ。

Sphinx.confdir

conf.py が含まれるディレクトリ。

Sphinx.doctreedir

ピクル化されたドクトリーを格納するためのディレクトリ。

Sphinx.outdir

ビルドされたドキュメントを格納するためのディレクトリ。

Sphinx.fresh_env_used

このビルドで新しい環境が作成されたかどうかを示すTrue/False、または環境がまだ初期化されていない場合はNone。

Sphinxのコアイベント

注釈

イベントコールバックAPI に移動しました。

Sphinxのバージョン確認

これを使用して、SphinxのAPI変更に合わせて拡張機能を調整してください。

sphinx.version_info = (8, 1, 0, 'beta', 0)

プログラムで使いやすくするためのバージョン情報。

5つの要素のタプル。Sphinxバージョン1.2.1 beta 3の場合、(1, 2, 1, 'beta', 3)になります。4番目の要素は、alpha、beta、rc、final のいずれかになります。final は常に最後の要素が 0 です。

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

Configオブジェクト

class sphinx.config.Config(config: dict[str, Any] | None = None, overrides: dict[str, Any] | None = None)

構成ファイルの抽象化。

Configオブジェクトは、すべての構成オプションの値を属性として利用できるようにします。

これは、Sphinx.config および sphinx.environment.BuildEnvironment.config 属性を通じて公開されます。たとえば、language の値を取得するには、app.config.language または env.config.language のいずれかを使用します。

テンプレートブリッジ

class sphinx.application.TemplateBridge

このクラスは、「テンプレートブリッジ」のインターフェースを定義します。つまり、テンプレート名とコンテキストを指定してテンプレートをレンダリングするクラスです。

init(builder: Builder, theme: Theme | None = None, dirs: list[str] | None = None) → None

テンプレートシステムを初期化するために、ビルダーによって呼び出されます。

builder はビルダーオブジェクトです。おそらく builder.config.templates_path の値を確認することになるでしょう。

theme は sphinx.theming.Theme オブジェクトまたは None です。後者の場合、dirs はテンプレートを検索する固定ディレクトリのリストにすることができます。

newest_template_mtime() → float

テンプレートの変更によって出力ファイルが古くなっているかどうかを判断するために、ビルダーによって呼び出されます。変更された最新のテンプレートファイルの mtime を返します。デフォルトの実装では 0 を返します。

render(template: str, context: dict) → None

指定されたコンテキスト（Python ディクショナリ）を持つファイル名として与えられたテンプレートをレンダリングするために、ビルダーによって呼び出されます。

render_string(template: str, context: dict) → str

指定されたコンテキスト（Python ディクショナリ）を持つ文字列として与えられたテンプレートをレンダリングするために、ビルダーによって呼び出されます。

例外

exception sphinx.errors.SphinxError

Sphinx エラーの基本クラス。

これは「ナイス」な例外の基本クラスです。このような例外が発生した場合、Sphinx はビルドを中止し、例外のカテゴリとメッセージをユーザーに表示します。

拡張機能は、カスタムエラーのためにこの例外から派生することが推奨されます。

SphinxError から派生していない例外は、予期しないものとして扱われ、トレースバックの一部（および一時ファイルに保存された完全なトレースバック）とともにユーザーに表示されます。

category

例外を文字列（「カテゴリ：メッセージ」）に変換する際に使用される、例外の「カテゴリ」の説明。サブクラスで適切に設定する必要があります。

exception sphinx.errors.ConfigError

構成エラー。

exception sphinx.errors.ExtensionError(message: str, orig_exc: Exception | None = None, modname: str | None = None)

拡張機能エラー。

exception sphinx.errors.ThemeError

テーマエラー。

exception sphinx.errors.VersionRequirementError

互換性のない Sphinx バージョンエラー。

前へ

Sphinx API

次へ

イベントコールバック API