sphinx_gallery.gen_gallery#
Sphinx-Gallery ジェネレーター。
ドキュメントのビルド時にギャラリーを生成するために、Sphinx に Sphinx-Gallery をアタッチします。
関数#
- sphinx_gallery.gen_gallery.clean_api_usage_files(app, exception)[ソース]#
api usage の .dot ファイルを削除します。
「build-finished」イベントに接続します。
- sphinx_gallery.gen_gallery.fill_gallery_conf_defaults(app, config, check_keys=True)[ソース]#
sphinx-gallery の設定をチェックし、デフォルト値を設定します。
これは、config-inited で早期に呼び出されるため、conf.py でキーが明示的に設定されていない場合でも、残りのコードは
sphinx_gallery_conf['binder']['use_jupyter_lab']のような処理を実行できます。
- sphinx_gallery.gen_gallery.generate_gallery_rst(app)[ソース]#
メインの例のギャラリー reStructuredText を生成します。
Sphinx-Gallery の設定を行い、例のディレクトリ（サブディレクトリの 1 レベルの深さまで）をスキャンして、例の reST ファイルを生成します。
ヘッダー/インデックスファイルを持つ各例のディレクトリとそのサブディレクトリ（サブセクションを作成します）を反復処理します。ギャラリーの例の ReST ファイルと index.rst ファイルを生成します。
nested_sections=True の場合、すべてのサブディレクトリに対して index.rst ファイルを生成します。これには、すべてのサブディレクトリの例への toctree リンクが含まれます。ルートの例ディレクトリの index.rst ファイルには、順番に以下のものが含まれます。
ルートギャラリーヘッダーとサムネイル、
ルートギャラリーのすべての例をリンクする toctree、
すべてのサブセクションのサブセクションヘッダーとそれに続くサブセクションのサムネイル、
ファイル末尾に、すべてのサブセクションのインデックスファイルにリンクする 2 番目の最後の toctree。
nested_sections=True の場合、例のディレクトリごとに 1 つの index.rst ファイルを生成します。これには、ルートギャラリーと各サブセクションのヘッダーが含まれ、各ヘッダーの後に、ルートギャラリー/サブセクションのすべての例をリンクする toctree が続きます。
- sphinx_gallery.gen_gallery.get_subsections(srcdir, examples_dir, gallery_conf, check_for_header=True)[ソース]#
ギャラリーのサブセクションのリストを返します。
- パラメーター:
srcdir (str) – conf.py を含むディレクトリへの絶対パス
examples_dir (str) – conf.py に対する例のディレクトリへのパス
gallery_conf (Dict[str, Any]) – Sphinx-Gallery 設定ディクショナリ。
check_for_header (bool) – GALLERY_HEADER ファイルを含むサブフォルダのみを返します。デフォルトは True
- 戻り値:
out – ギャラリーのサブセクションのフォルダ名のソートされたリスト
- 戻り値の型:
- sphinx_gallery.gen_gallery.setup_template_link_getters(app, pagename, templatename, context, doctree)[ソース]#
ダウンロードおよびランチャーリンクのゲッターをセットアップします。
ゲッターは、テンプレートで使用できるように、sphinx コンテキストに追加されます。
- sphinx_gallery.gen_gallery.summarize_failing_examples(app, exception)[ソース]#
失敗した例のリストを収集し、トレースバックと共に出力します。
失敗した例があった場合は ValueError を発生させます。
- sphinx_gallery.gen_gallery.touch_empty_backreferences(app, what, name, obj, options, lines)[ソース]#
空のバックリファレンスの例ファイルを生成します。
これにより、autodoc によって解析されているクラス/モジュールにギャラリーの例がない場合、インクルードエラー/警告が回避されます。
- sphinx_gallery.gen_gallery.update_gallery_conf_builder_inited(app)[ソース]#
builder-inited で sphinx-gallery 設定を更新します。
- sphinx_gallery.gen_gallery.write_api_entries(app, what, name, obj, options, lines)[ソース]#
api エントリを _sg_api_entries 設定に書き込みます。
autodoc-process-docstring イベントに接続します。
- パラメーター:
app – Sphinx アプリケーションオブジェクト。
what (str) – ドキュメント文字列が属するオブジェクトのタイプ。「module」、「class」、「exception」、「function」、「method」、「attribute」のいずれか。
name – オブジェクトの完全修飾名。
obj – オブジェクト自体。
options – ディレクティブに指定されたオプション: 同じ名前のフラグオプションが auto ディレクティブに指定された場合は、継承されたメンバー、undoc_members、show_inheritance、no-index の属性を持つオブジェクトで、true です。
lines – ドキュメント文字列の行。上記を参照。
- sphinx_gallery.gen_gallery.write_api_entry_usage(app, docname, source)[ソース]#
使用されているAPIエントリと未使用のAPIエントリを記述したHTMLページを書き込みます。
autodocによって使用されるAPIエントリのみをドキュメント化およびグラフ化するには、autodocが完了するのを待って、
source-readイベントにフックする必要があります。これにより、rstからのテキストがインターセプトされ、変更できるようになります。空のファイルにのみ触れたため、1）未使用のすべてのAPIエントリのリストと、モジュールごとの未使用のAPIエントリ数のグラフ、および2）例で使用されているAPIエントリのリスト（それぞれにそのAPIエントリが使用されている例のサブリストを含む）、およびモジュール内のすべてのAPIエントリをそれらが使用されている例に接続するグラフを追加する必要があります。- パラメーター:
app – Sphinx アプリケーションオブジェクト。
docname – 現在解析中のドキュメントのドキュメント名。
source – 単一の要素がソースファイルの内容であるリスト
- sphinx_gallery.gen_gallery.write_computation_times(gallery_conf, target_dir, costs)[ソース]#
計算時間をsg_execution_times.rstに書き込みます。
- パラメーター:
gallery_conf (Dict[str, Any]) – Sphinx-Gallery 設定ディクショナリ。
target_dir (str | None) – 例のPythonソースファイルがあるディレクトリへのパス。
costs (List[Dict]) – 計算コストとパスの辞書のリスト。詳細についてはgen_rst.pyを参照してください。
- sphinx_gallery.gen_gallery.write_junit_xml(gallery_conf, target_dir, costs)[ソース]#
例の実行時間、成功、失敗のJUnit XMLファイルを書き込みます。
- パラメーター:
gallery_conf (Dict[str, Any]) – Sphinx-Gallery 設定ディクショナリ。
target_dir (Union[str, pathlib.Path]) – ビルドディレクトリ。
costs (List[Tuple[Tuple[float], str]]) – 計算コストとパスの辞書のリスト。詳細についてはgen_rst.pyを参照してください。