アプリケーションAPI

各Sphinx拡張モジュールはPythonモジュールであり、少なくとも1つである setup() 機能します。この関数は，初期化時にSphinxプロセスのアプリケーションオブジェクトを表す1つのパラメータ呼び出しを用いる.

class sphinx.application.Sphinx

このアプリケーションオブジェクトは，以下に述べる共通APIを持つ.

子機設定

これらの方法は一般的に拡張されています setup() 機能します。

Sphinxを使用した拡張APIの例は、 sphinx.ext 小包です。

Sphinx.setup_extension(name)

Sphinx拡張モジュールを導入して設定します。

ロード·モジュールが提供する拡張 name それがそうです。もしあなたの内線に他の内線が提供する機能が必要な場合は、この機能をご利用ください。2回呼び出されると，操作は実行されない.

Sphinx.require_sphinx(version)

必要であれば、Sphinxバージョンをチェックしてください。

比較する． バージョン (そうでなければならない major.minor バージョン文字列、例えば '1.1' )を構築しすぎた場合には構築を中止する.

バージョン 1.0 で追加.

Sphinx.connect(event, callback)

レジスタ.レジスタ コールバック. 以下の場合に呼び出します 事件 排出されます

利用可能なコアイベントとコールバック関数パラメータの詳細については、参照されたい ライオンの顔像の中心的な事件 それがそうです。

登録されたコールバックは以下の手順でイベントで呼び出される 優先度. 登録もあります。優先順位は昇順である.

この方法は、パラメータとして使用可能な“モニタID”を返す。 disconnect() それがそうです。

バージョン 3.0 で変更: 支持する. 優先度.

Sphinx.disconnect(listener_id)

登録コールバック方式をキャンセルする listener_id それがそうです。

Sphinx.add_builder(builder)

新しい建築業者を登録する。

建設者. 継承しなければなりません Builder それがそうです。

もし 超覆. 本当です。与えられました。 建設者. 同じ名前を持つビルダが実装されていても，強制的に実装される.

バージョン 1.8 で変更: 増列する. 超覆. キーワード。

Sphinx.add_config_value(name, default, rebuild)

構成値を登録します。

これは、Sphinxが新しい値を識別し、それに応じてデフォルト値を設定するために必要である。♪the name 拡張子は、競合を回避するためにプレフィックスとして使用されるべきである。♪the 約束を破る. 値は任意のPythonオブジェクトとすることができます。文字列値 再建する. 次の値の1つでなければなりません

• 'env' 設定中の変更が文書解析時にのみ有効であれば，環境全体を再構築しなければならないことを意味する.

• 'html' 設定を変更するにはHTML文書を完全に再生成する必要がある.

• '' 設定を変更すれば、特別な再構成は必要ありません。

バージョン 0.6 で変更: 変更されました 再建する. 単純なブール値から '' あるいは…。 'env' )を文字列に変換します。しかし、ブール値はまだ内部で受け入れられて変換されている。

バージョン 0.4 で変更: もし 約束を破る. 値が呼び出し可能である場合は，デフォルト値を得るためにconfigオブジェクトをそのパラメータとして呼び出す.これは、他の値の構成値に依存して、そのデフォルト値を実装するために使用することが

Sphinx.add_event(name)

名前を登録する name それがそうです。

これはそれを放出するために必要だ。

Sphinx.set_translator(name, translator_class)

Docutils変換器クラスを登録または上書きします。

これは，カスタム出力トランスレータを登録したり，内蔵トランスレータを置き換えるために用いられる.これにより、拡張モジュールがカスタムトランスレータを使用してトランスレータのカスタムノードを定義することができます(参照 add_node() ）。

もし 超覆. 本当です。与えられました。 translator_class 翻訳機が使用されても強制的にインストールされています name インストールされています。

バージョン 1.3 で追加.

バージョン 1.8 で変更: 増列する. 超覆. キーワード。

Sphinx.add_node(node, \*\*kwds)

Docutilsノードクラスを登録する.

これはDocutils内部に必要だ。将来的にはこれを用いて解析された文書中のノードを検証することも可能である.

Node visitor functions for the Sphinx HTML, LaTeX, text and manpage writers can be given as keyword arguments: the keyword should be one or more of 'html', 'latex', 'text', 'man', 'texinfo' or any other supported translators, the value a 2-tuple of (visit, depart) methods. depart can be None if the visit function raises docutils.nodes.SkipNode. Example:

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))

明らかに，アクセス機メソッドを指定していないトランスレータは，翻訳する文書中でノードに遭遇した場合にノードをブロックする.

もし 超覆. 本当です。与えられました。 node 同じ名前を持つノードがすでに実装されていても，強制的に実装される.

バージョン 0.5 で変更: アクセス関数を提供するキーワードパラメータの支援を加えた.

Sphinx.add_enumerable_node(node, figtype, title_getter=None, \*\*kwds)

Docutilsノードクラスをnumfigオブジェクトとして登録する.

Sphinxは自動的にノード番号となる.そしてユーザーは使用することができます 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関数である.これは、列挙可能なノードのインスタンスを受け入れ、そのタイトルを文字列の形態で返さなければならない。タイトルが参照に用いられるデフォルトタイトル ref それがそうです。デフォルトの場合、Sphinx検索 docutils.nodes.caption あるいは…。 docutils.nodes.title タイトルとしてノードから削除する.

他のキーワードパラメータはノードアクセス関数に用いられる.ご参照ください Sphinx.add_node() もっと細かいことを知っています。

もし 超覆. 本当です。与えられました。 node 同じ名前を持つノードがすでに実装されていても，強制的に実装される.

バージョン 1.4 で追加.

Sphinx.add_directive(name, directiveclass)

Docutilsコマンドを登録します。

name 予想される指示名でなければならない。 cls 命令クラスであり、それは継承されています docutils.parsers.rst.Directive それがそうです。詳細については、ご参照ください the Docutils docs それがそうです。

たとえば，名前のカスタムコマンドは 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):
    add_directive('my-directive', MyDirective)

もし 超覆. 本当です。与えられました。 cls 名前があっても name インストールされています。

バージョン 0.6 で変更: 現在Docutils 0.5スタイルのコマンドクラスをサポートしています。

バージョン 1.8 で非推奨: Docutils 0.4スタイル(関数ベース)コマンドでサポートすることは推奨されていません。

バージョン 1.8 で変更: 増列する. 超覆. キーワード。

Sphinx.add_role(name, role)

Docutilsキャラクターを登録します。

name 源に出てくるキャラクターの名前でなければならない。 role 役割機能。参考にする Docutils documentation より多くの情報を得ることができます

もし 超覆. 本当です。与えられました。 role 名前があっても name インストールされています。

バージョン 1.8 で変更: 増列する. 超覆. キーワード。

Sphinx.add_generic_role(name, nodeclass)

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

Docutilsロールを登録し、その内容を所与のノードから内外に包装する以外は何もしない 復号化されていない それがそうです。

もし 超覆. 本当です。与えられました。 復号化されていない 名前があっても name インストールされています。

バージョン 0.6 で追加.

バージョン 1.8 で変更: 増列する. 超覆. キーワード。

Sphinx.add_domain(domain)

登録ドメイン。

与えられた 域 (それはクラスでなければならない；より正確には Domain )は、ライオンの顔像として知られています。

もし 超覆. 本当です。与えられました。 域 同名のドメインが実装されていても，強制的に実装される.

バージョン 1.0 で追加.

バージョン 1.8 で変更: 増列する. 超覆. キーワード。

Sphinx.add_directive_to_domain(domain, name, directiveclass)

Docutilsコマンドをドメインに登録します。

像 add_directive() しかし，この命令は名前のドメインに追加される. 域 それがそうです。

もし 超覆. 本当です。与えられました。 指令 名前があっても name インストールされています。

バージョン 1.0 で追加.

バージョン 1.8 で変更: 増列する. 超覆. キーワード。

Sphinx.add_role_to_domain(domain, name, role)

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

像 add_role() しかし，このロールは名前のドメインに追加される. 域 それがそうです。

もし 超覆. 本当です。与えられました。 role 名前があっても name インストールされています。

バージョン 1.0 で追加.

バージョン 1.8 で変更: 増列する. 超覆. キーワード。

Sphinx.add_index_to_domain(domain, index)

登録ドメインのカスタムインデックス.

カスタムを追加する 指標. クラスは名前のドメインに初期化される 域 それがそうです。 指標. そうでなければならない子類 Index それがそうです。

もし 超覆. 本当です。与えられました。 指標. 同名インデックスが実装されていても，強制的にインストールされる.

バージョン 1.0 で追加.

バージョン 1.8 で変更: 増列する. 超覆. キーワード。

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

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

この方法は新しいものを追加するための非常に便利な方法です object 交差引用可能なタイプ.これは、以下の動作を実行する。

• 新しいコマンドを作成する(名前は ディレクトリ名 )は、オブジェクトを記録するために使用される。以下のような場合には，インデックス項目を自動的に追加する 索引テンプレート 空ではない；与えられた場合，それは正確に含まれなければならない %s それがそうです。テンプレートの解釈方法については、以下の例を参照されたい。

• 新しいキャラクターを作る 役名. )これらのオブジェクト記述を交差参照します。

• もしあなたが提供すれば parse_node これは，文字列とdocutilsノードを受け取る関数でなければならず，文字列から解析された子ノードを用いてノードを充填しなければならない.そして，交差参照と索引項で使用する項の名前を返さなければならない.ご参照ください conf.py 本文書のソースコードファイルには一例が提供されている.

• ♪the 対象名 (指定されていなければ、デフォルトで判断します ディレクトリ名 )名前付けオブジェクトのタイプ。これは、例えば検索結果にオブジェクトを列挙する際に使用される。

例えば、カスタム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

引用ノードはクラスに属する literal (したがって、コードの適切な状況に応じて比例フォントで提示されます)、あなたが与えない限り ref_nodeclass パラメータは，このパラメータはdocutilsノードクラスでなければならない.最も有用なのは docutils.nodes.emphasis あるいは…。 docutils.nodes.strong --ご利用いただけます docutils.nodes.generated もしあなたがこれ以上のテキスト修飾を必要としなければ。テキストが文字(例えば、スマート引用符の置き換えがない)とみなされるべきであるが、タイプライター様式がない場合は、使用してください sphinx.addnodes.literal_emphasis あるいは…。 sphinx.addnodes.literal_strong それがそうです。

ロール内容については、標準的なSphinxロールと同じ文法的可能性を持っています(参照 交差引用文法 ）。

もし 超覆. Trueでは，同名のobject_typeが実装されていても，与えられたobject_typeを強制的に実装する.

バージョン 1.8 で変更: 増列する. 超覆. キーワード。

Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='')

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

この方法は非常に似ています 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 命令は節である必要はない。)

もし 超覆. Trueであれば，同じ名前を持つCrossRef_typeが実装されていても，与えられたCrossRef_typeを強制的に実装する.

バージョン 1.8 で変更: 増列する. 超覆. キーワード。

Sphinx.add_transform(transform)

登録は解析後に適用するDocutils変換である.

標準Docutilsを追加する Transform 子類. 変換する. SphinxがREST文書を解析して適用した変換リストに追加する.

Sphinx変換の優先度範囲クラス

優先度.	ライオンの顔像の主な用途
0-99	Docutilsにより無効ノードを修復する.文書木を翻訳する。
100-299	調製する.
300-399	早い時間に
400-699	幹線道路.
700-799	後処理をする。テキストと引用の締め切りを修正する。
800-899	引用と引用のノードを収集する.ドメイン処理。
900-999	完成して掃除する。

参考文献： `Transform Priority Range Categories`_ _

Sphinx.add_post_transform(transform)

書き込む前に適用するDocutils変換を登録します。

標準Docutilsを追加する Transform 子類. 変換する. Sphinxが文書を作成する前に適用される変換リストに追加します。

Sphinx.add_js_file(filename, **kwargs)

HTML出力に含まれるJavaScriptファイルを登録する.

増列する. ファイル名 デフォルトHTMLテンプレートに含まれるJavaScriptファイルリストに追加します。ファイル名は、HTMLに対して静的なパス、またはシナリオ付き完全URIでなければならない。もしキーワードパラメータが body その値は <script> ラベル。追加のキーワードパラメータは <script> ラベル。

例：：

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

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

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

バージョン 0.5 で追加.

バージョン 1.8 で変更: 名前を立て直す app.add_javascript() それがそうです。これは，スクリプトタグの属性としてキーワードパラメータを許す.

Sphinx.add_css_file(filename, **kwargs)

HTML出力に含まれるスタイルテーブルを登録する.

増列する. ファイル名 デフォルトHTMLテンプレートに含まれるCSSファイルリストに追加します。ファイル名は、HTMLに対して静的なパス、またはシナリオ付き完全URIでなければならない。属性もキーワードパラメータを受け取ります <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" />

バージョン 1.0 で追加.

バージョン 1.6 で変更: 任意選択. alternate and/or title attributes can be supplied with the alternate (of boolean type) and title (a string) arguments. The default is no title and alternate = False. For more information, refer to the documentation それがそうです。

バージョン 1.8 で変更: 名前を立て直す app.add_stylesheet() それがそうです。これは，キーワードパラメータをリンクラベルの属性として許可する.

Sphinx.add_latex_package(packagename, options=None)

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

増列する. 包名. LaTeXソースコードに含まれるパケットリストに追加する.もしあなたが提供すれば オプション そしてそれは 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, lexer)

ソースコードに新しい字句解析器を登録する.

使用 語法解析器 与えられた言語を用いたコードブロックを強調表示するには，以下の操作を実行してください 別名. それがそうです。

バージョン 0.6 で追加.

バージョン 2.1 で変更: Lexerクラスをパラメータとする.Sphinx-3.xの前には，形態素解析器の用例がサポートされている

Sphinx.add_autodocumenter(cls)

Autocに新たなDocumenterクラスを拡張登録する.

増列する. cls として sphinx.ext.autodoc 延期する。それはそうでなければならない sphinx.ext.autodoc.Documenter それがそうです。これは新しいタイプのオブジェクトを自動的に記録することを可能にする。どのようにサブクラス化するかの例については，autocモジュールのソースコードを参照されたい. Documenter それがそうです。

もし 超覆. 本当です。与えられました。 cls 同名の文書器が設置されていても，強制的に取り付けられる.

課題

文書器と子類化のための実文書の追加

バージョン 0.6 で追加.

バージョン 2.2 で変更: 増列する. 超覆. キーワード。

Sphinx.add_autodoc_attrgetter(type, getter)

新しいのを登録する getattr -Autodoc拡張LIKE関数。

増列する. ゲッター. 私たちが持っていなければならないのは getattr() 内蔵，インスタンスの対象となるautoc属性getter typ それがそうです。そして，autocがタイプ属性を取得する必要があるすべての場合はこの関数で処理する. getattr() それがそうです。

バージョン 0.6 で追加.

Sphinx.add_search_language(cls)

HTML検索インデックスに新しい言語を登録する.

増列する. cls それはサブクラスでなければなりません sphinx.search.SearchLanguage これは，HTML全文検索インデックスを構築するための支援言語である.クラスは1つなければならない lang 属性，その属性は使用すべき言語を示す.見 html_search_language それがそうです。

バージョン 1.1 で追加.

Sphinx.add_source_suffix(suffix, filetype)

登録元ファイルの接尾辞

相同 source_suffix それがそうです。ユーザは、設定を使用してこの設定を上書きすることができる。

もし 超覆. 本当です。与えられました。 接尾辞 同じ接尾辞が取り付けられていても，強制的に取り付けられる

バージョン 1.8 で追加.

Sphinx.add_source_parser(parser)

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

もし 超覆. 本当です。与えられました。 解析器 すでに同じ接尾辞の解析器が実装されていても，強制的に実装される.

バージョン 1.4 で追加.

バージョン 1.8 で変更: 接尾辞 パラメータは既に使用されていない.それはただ受け入れるだけだ 解析器 論争する。使用 add_source_suffix() APIは接尾辞を登録する

バージョン 1.8 で変更: 増列する. 超覆. キーワード。

Sphinx.add_env_collector(collector)

登録環境収集器クラス。

参考にする 環境収集器API それがそうです。

バージョン 1.6 で追加.

Sphinx.add_html_theme(name, theme_path)

HTMLトピックを登録する。

♪the name テーマ名であり path テーマの完全パスです(参考： あなたのテーマをPythonパッケージとして配布します ）。

バージョン 1.6 で追加.

Sphinx.add_html_math_renderer(name, inline_renderers, block_renderers)

HTMLに数学レンダラを登録する.

♪the name 数学レンダラーの名前です。どちらもある inline_renderers そして block_renderers HTMLコンパイラとして用いられるアクセス関数：前者は連結数学ノードに用いられる. (nodes.math )、後者はブロック数学ノードに使用される (nodes.math_block ）。訪問者関数については、参照されたい add_node() もっと細かいことを知っています。

バージョン 1.8 で追加.

Sphinx.add_message_catalog(catalog, locale_dir)

メッセージリストを登録する。

♪the カタログ. ディレクトリの名前であり locale_dir メッセージリストの基本経路である.詳細については、ご参照ください sphinx.locale.get_translation() それがそうです。

バージョン 1.8 で追加.

Sphinx.is_parallel_allowed(typ)

並列処理を許可するかどうかをチェックする.

typ 1つの加工タイプです 'read' あるいは…。 'write' それがそうです。

exception sphinx.application.ExtensionError

拡張APIに問題が発生すると，これらのすべての方法がこの異常を引き起こす.

事件を発している

class sphinx.application.Sphinx

emit(event, \*arguments)

発射する. 事件 そして通過します 立論. コールバック関数に追加します。

すべてのコールバックの返り値をリスト形式で返す.拡張でコアSphinxイベントを出さないで！

バージョン 3.1 で変更: 増列する. allowed_exceptions 直通パス例外を指定するには、以下の操作を実行してください

emit_firstresult(event, \*arguments)

発射する. 事件 そして通過します 立論. コールバック関数に追加します。

最初に戻らないコールバックの結果に戻ります None それがそうです。

バージョン 0.5 で追加.

バージョン 3.1 で変更: 増列する. allowed_exceptions 直通パス例外を指定するには、以下の操作を実行してください

Sphinx実行時情報

アプリケーションオブジェクトは，実行時情報を属性として提供する.

Sphinx.project

目標項目。見 Project それがそうです。

Sphinx.srcdir

ソースディレクトリ。

Sphinx.confdir

以下の内容を含むディレクトリ conf.py それがそうです。

Sphinx.doctreedir

塩漬け文書木を格納するためのディレクトリ。

Sphinx.outdir

構築文書を格納するためのディレクトリ.

ライオンの顔像の中心的な事件

これらの事件は核心的に知られている。表示されたパラメータは，登録されたイベントハンドラに提供される.使用 Sphinx.connect() 拡張の setup 関数(注意してください、 conf.py 1つを持つこともできます setup 関数)ハンドラをイベントに接続する.例：

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

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

以下に構築過程で発生する個々のイベントの概要を示す.以下のリストには、イベント名、そのコールバックパラメータ、およびイベントの入出力タイプが含まれる。

1. event.config-inited(app,config)
2. event.builder-inited(app)
3. event.env-get-outdated(app, env, added, changed, removed)
4. event.env-before-read-docs(app, env, docnames)

for docname in docnames:
   5.  event.env-purge-doc(app, env, docname)
   if doc changed and not removed:
      6. source-read(app, docname, source)
      7. run source parsers: text -> docutils.document (parsers can be added with the app.add_source_parser() API)
      8. apply transforms (by priority): docutils.document -> docutils.document
         - event.doctree-read(app, doctree) is called in the middly of transforms,
           transforms come before/after this event depending on their priority.
9. (if running in parallel mode, for each process) event.env-merged-info(app, env, docnames, other)
10. event.env-updated(app, env)
11. event.env-get-updated(app, env)
12. event.env-check-consistency(app, env)

# The updated-docs list can be builder dependent, but generally includes all new/changed documents,
# plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
# For builders that output a single page, they are first joined into a single doctree before post-transforms/doctree-resolved
for docname in updated-docs:
   13. apply post-transforms (by priority): docutils.document -> docutils.document
   14. event.doctree-resolved(app, doctree, docname)
       - (for any reference node that fails to resolve) event.missing-reference(env, node, contnode)
       - (for any reference node that fails to resolve) event.warn-missing-reference(domain, node)

15. Generate output files
16. event.build-finished(app, exception)

以下にこれらのイベントのより詳細なリストを示す.

builder-inited(app)

生成器オブジェクトを作成する際に励起されます。次のような形で選択できます app.builder それがそうです。

config-inited(app, config)

構成オブジェクトが初期化されたときに呼び出されます。

バージョン 1.8 で追加.

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

Emitted when the environment determines which source files have changed and should be re-read. added, changed and removed are sets of docnames that the environment has determined. You can return a list of docnames to re-read in addition to these.

バージョン 1.1 で追加.

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

ソースファイルのすべてのトラッキングが環境から消去されるべきである場合(すなわち、ソースファイルが削除された場合、または再読み取りの前に)が発行される。これは，自分のキャッシュを環境属性に保存する拡張に適している.

たとえば，環境中のすべてのモジュールは1つのキャッシュを持つ.ソースファイルの変更後、モジュールがファイルから削除された可能性があることを宣言するので、ファイルのキャッシュエントリが消去されます。

バージョン 0.5 で追加.

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

環境が追加および変更されたすべてのファイルのリストを決定した後、これらのファイルを読み込む前に発行されます。これは、著者が文書名リストを並べ替えることを可能にします( 在位する. )を追加するか、またはSphinxが変更されていないと考えられるより多くの文書名を追加する(ただし、含まれていないいかなる文書名も追加することはない env.found_docs ）。

ファイル名を削除することもできます；Sphinxが変更されたファイルを変更されていないファイルと見なすので、この操作を実行する際には気をつけなければなりません。

バージョン 1.3 で追加.

source-read(app, docname, source)

ソースファイルを読み込む際に発行します。♪the 源. パラメータはリストであり、その単一の要素はソースファイルの内容である。内容を処理し、これを置き換えてソースコードレベルの変換を実現することができます。

例えば使用する場合 $ 記号はLaTeXのように内部結合数学を分離します正規表現を使って置き換えることができます $...$ vt.から. :math:`... `.

バージョン 0.5 で追加.

object-description-transform(app, domain, objtype, contentnode)

オブジェクト記述命令を実行する際に発行する.♪the 域 そして 対象タイプ パラメータは，オブジェクトのオブジェクト記述を指示する文字列である.と…。 コンテンツノード 対象の内容です。それは在位修正を行うことができる。

バージョン 2.4 で追加.

doctree-read(app, doctree)

文書木が環境解析および読み取りされ、酸洗直前に発行された。♪the 文書木. その場で修正できます。

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

オブジェクトへの交差参照が解析できない場合には発火する.イベントハンドラが参照を解析できる場合、ノードを置き換えて文書木に挿入するために、新しいdocutilsノードを返すべきである。 node それがそうです。通常このノードは reference 以下を含むノード 連絡ノード. 私が子供の頃。ハンドラが交差参照を解析できなければ返すことができる. None 他の処理プログラムに試したり誘発させたりします NoUri 他のハンドラがこのクロスリファレンスについて解析されていない警告を試み，キャンセルすることを防ぐ.

パラメータ

• env -- 環境を構築する (app.builder.env ）。

• node -- The pending_xref node to be resolved. Its attributes reftype, reftarget, modname and classname attributes determine the type and target of the reference.

• contnode -- 将来の引用ではテキストやフォーマットを携帯し，かつ返す引用ノードの子ノードであるべきノードである.

バージョン 0.5 で追加.

warn-missing-reference(app, domain, node)

対象への交差引用が解析できない場合に発行する missing-reference それがそうです。イベントハンドラが失われた参照を警告することができる場合、それは戻るべきである。 True それがそうです。

バージョン 3.4 で追加.

doctree-resolved(app, doctree, docname)

環境が文書木を“解析”したときに発行される，すなわちすべての引用を解析してTOCに挿入されている.♪the 文書木. その場で修正できます。

ここでは，ライタに訪問者メソッドのないカスタムノードを入れ替える場所であり，ライタがそれらに遭遇した場合には，誤りを招くことはない.

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

このイベントは、文書並列読み出しが有効になった場合にのみ起動される。ある文書を読み込んだ各子プロセスに対して，それは1回発行される.

このイベントは，データを環境に格納するカスタム位置の拡張で処理しなければならない.そうでなければ，主プロセス中の環境は子プロセスに格納されている情報を知らない.

他にも 子プロセスからの環境オブジェクトです env 環境からの主な過程です。 文書名. これは、サブプロセスで読み取られた文書名のセットである。

バージョン 1.3 で追加.

env-updated(app, env)

以下の操作を実行する際に発行する. update() 方法，すなわち，環境とすべての文書木が現在最新である.

処理プログラムから繰り返し可能なdocnameを返すことができます。そして、これらの文書は更新されたとみなされ、作成段階で作成される(再作成される)。

バージョン 0.5 で追加.

バージョン 1.3 で変更: 現在，ハンドラの返り値を使用する.

env-check-consistency(app, env)

整合性チェックフェーズ時に発行される.文書全体のメタデータの一貫性を確認することができます。

バージョン 1.6 で追加: 一人として 試験的に 事件

html-collect-pages(app)

HTML生成器が非文書ページの作成を開始したときに発行される.このイベントから以下を含む反復値を返すことで、書き込むページを追加することができます (pagename, context, templatename) それがそうです。

バージョン 1.0 で追加.

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

HTMLビルダがテンプレートをレンダリングするためのコンテキスト辞書を作成したときに発行される--これは、コンテキストにカスタム要素を追加するために使用することができる。

♪the ページ名 パラメータは，提示されているページの仕様名，すなわちなしである. .html 接尾辞は，パス区切りとしてスラッシュを用いる.♪the テンプレート名 表示されるテンプレートの名前は 'page.html' RESTドキュメント内のすべてのページに使用されます。

♪the 文脈. パラメータは、ページの値を提示するためにテンプレートエンジンに提供される辞書であり、カスタム値を含むように修正することができる。キーは文字列でなければなりません。

♪the 文書木. パラメータはREST文書からページを作成する際の文書木となる. None HTMLテンプレートからのみページを作成する場合.

処理プログラムから文字列を返して置き換えることができます 'page.html' このページのHTMLテンプレートとする.

注釈

以下のように特定のページのJS/CSSファイルをインストールすることができます Sphinx.add_js_file() そして Sphinx.add_css_file() バージョン3.5.0から開始します。

バージョン 0.4 で追加.

バージョン 1.3 で変更: 返却値は、現在、テンプレート名を指定することができます。

build-finished(app, exception)

生成が完了した後，Sphinxが退出する前に発行され，通常クリーニングに用いられる.生成過程が異常を起こした場合でもこのイベントを誘発し，与えられる. 例外 論争する。イベントハンドラの実行後，この例外はアプリケーションで再起動される.構築過程に異常がなければ 例外 はい。はい。 None それがそうです。これは，例外状態に応じてクリーニング動作をカスタマイズすることを可能にする.

バージョン 0.5 で追加.

Sphinxバージョンをチェックする

これを使用して、SphinxのAPI変更に拡張を適応させます。

sphinx.version_info = (3, 4, 3, 'final', 0)

バージョン情報は、使用をより良くプログラミングするために使用される。

A tuple of five elements; for Sphinx version 1.2.1 beta 3 this would be (1, 2, 1, 'beta', 3). The fourth element can be one of: alpha, beta, rc, final. final always has 0 as the last element.

バージョン 1.2 で追加: バージョン1.2の前に、文字列をチェックしてください sphinx.__version__ それがそうです。

配置対象

class sphinx.config.Config(config: Dict[str, Any] = {}, overrides: Dict[str, Any] = {})

プロファイルが抽象的です。

配置対象は，すべての配置値の値を属性として使用できるようにする.

これは sphinx.application.Application.config そして sphinx.environment.Environment.config 属性です。例えば取得するには language 以下のいずれかのオプションを使用してください app.config.language あるいは…。 env.config.language それがそうです。

型枠橋

class sphinx.application.TemplateBridge

このクラスは、テンプレート名およびコンテキストが与えられた場合にテンプレートのクラスを提示する“テンプレートブリッジ”のインタフェースを定義する。

init(builder: Builder, theme: sphinx.theming.Theme = None, dirs: List[str] = None) → None

テンプレートシステムを初期化するためにビルダによって使用される.

建設者. 構築されたオブジェクトであることを確認したいかもしれません builder.config.templates_path それがそうです。

主旋律. これは sphinx.theming.Theme 対象またはなし；後者の場合， 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は構築を中止し、異常種別およびメッセージをユーザに表示する。

拡張がこの異常から派生してそのカスタムミスを奨励する。

例外 not 派生自. SphinxError インシデントとみなされ，部分バックトラック(および一時ファイルに保存された完全バックトラック)に従ってユーザに表示される.

category

例外CATEGORYの記述は，例外を文字列(“CATEGORY：MESSAGE”)に変換するためのものである.サブクラスにそれに応じて設定されなければならない。

exception sphinx.errors.ConfigError

配置が間違っています。

exception sphinx.errors.ExtensionError(message: str, orig_exc: Optional[Exception] = None)

誤りを拡張する。

exception sphinx.errors.ThemeError

主題が間違っている。

exception sphinx.errors.VersionRequirementError

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