設定#

Sphinx-Gallery の設定とカスタマイズは、主に conf.py ファイルで指定された辞書を使用して行われます。可能なキーのリストは下記に記載されており、後続のセクションで詳細に説明されています。

これらのフラグを使用する場合は、ソース Python ファイルが生成された HTML と iPython ノートブックと等価であることを確認することがベストプラクティスです（つまり、.py == .html == .ipynb を確認してください）。この原則は、必要に応じて、ケースバイケースで破るべきです。

設定オプション#

グローバル conf.py 設定#

Sphinx の conf.py ファイル内の sphinx_gallery_conf 辞書内で設定できる Sphinx-Gallery の設定オプション。

ギャラリーファイルと順序

実行例

相互参照

画像とサムネイル

計算コスト

Jupyter ノートブックとインタラクティビティ

外観

その他

例の中の設定#

いくつかのオプションは、ファイルごとに設定または上書きすることもできます。

いくつかのオプションは、ファイル内のコードブロックごとに設定できます。

いくつかのオプションは、ファイル内の行ごとに設定できます： - # sphinx_gallery_start_ignore と # sphinx_gallery_end_ignore (コード行の非表示)

レンダリングされた例からファイル内の設定コメントを非表示にするには、設定コメントの削除も参照してください。

ビルドオプション#

一部のオプションは、ビルド実行ステップ（例：Makefile を使用）中に設定できます。

CSS の変更#

いくつかの項目は CSS で直接調整できます。

警告の削除#

警告が取得されてビルドされたドキュメントに含まれるのを防ぐには、conf.py ファイルで warnings パッケージを使用できます。例えば、Matplotlib の agg に関する特定の警告を削除するには、

import warnings

warnings.filterwarnings("ignore", category=UserWarning,
                        message='Matplotlib is currently using agg, which is a'
                                ' non-GUI backend, so cannot show the figure.'
                                '|(\n|.)*is non-interactive, and thus cannot be shown')

を conf.py ファイルに追加します。

上記の Matplotlib の警告は、デフォルトで削除されます。

呼び出し可能オブジェクトのインポート#

インスタンス化されたクラス、クラス、または関数である Sphinx-Gallery の設定値は、オブジェクトへの完全修飾名文字列として渡す必要があります。オブジェクトは Sphinx-Gallery でインポート可能である必要があります。

これを実現する一般的な方法は 2 つあります。

  1. パッケージでオブジェクトを定義します。例えば、def my_sorter 関数を記述し、mymod/utils.py に配置し、次のように使用します。

    sphinx_gallery_conf = {
#...,
"minigallery_sort_order": "mymod.utils.my_sorter",
#...
}

  2. ドキュメントでオブジェクトを定義します。例えば、別のパスにドキュメント固有のものを追加し、ビルド時に解決できるようにします。例えば、doc/sphinxext.py ファイルを作成し、関数を次のように定義します。

    def plotted_sorter(fname):
    return not fname.startswith("plot_"), fname

    そして、設定で次のように設定します。

    sys.path.insert(0, os.path.dirname(__file__))

sphinx_gallery_conf = {
#...,
"minigallery_sort_order": "sphinxext.plotted_sorter",
#...
}

    Sphinx-Gallery は、doc/ ディレクトリがパスの先頭にあるため、"sphinxext.plotted_sorter" を plotted_sorter オブジェクトに解決します。

sphinx_gallery.sorting.FileNameSortKey など、組み込みのクラスは、"FileNameSortKey" のようなより短い直接的なエイリアス文字列を使用して使用できます（詳細は ギャラリー例をソートする を参照してください）。

注記

Sphinx-Gallery >0.16.0 は、Sphinx >7.3.0 の conf.py ファイルのキャッシングとシリアル化チェックに対する変更に対応して、完全修飾名文字列の使用をサポートしています。

これは、ビルド全体で __repr__ が安定するように設定値にクラスインスタンスを使用するという以前の方法が、名前文字列を介して設定値を渡す場合、冗長であることを意味します。名前文字列を使用する場合、設定オブジェクトは関数であるだけで済みます。

安定した __repr__ の確保#

後方互換性のために、Sphinx-Gallery は、インポート可能な名前文字列 の代わりに、特定の設定値を呼び出し可能オブジェクトにすることを許可しています。

呼び出し可能オブジェクトを使用する場合は、実行全体で __repr__ が安定していることを確認する必要があります。Sphinx は、ビルド環境が変更されたかどうか、したがってすべてのドキュメントを書き直す必要があるかどうかを、md5(str(obj).encode()).hexdigest() を使用して設定値を検査することで判断します（sphinx/builders/html.py）。Python のデフォルトのクラスインスタンスには、__repr__ にメモリアドレスが含まれているため、一般的に __repr__ は各ビルドで変更されます。

呼び出し可能オブジェクトは、安定した __repr__ メソッドを定義するクラスである必要があります。例えば、sphinx_gallery.sorting.ExplicitOrder の安定性は、カスタム __repr__ によって保証されます。

def __repr__(self):
    return '<%s: %s>' % (self.__class__.__name__, self.ordered_list)

したがって、ファイルは指定された順序付きリストが変更された場合にのみ再ビルドされます。

複数のギャラリーの管理#

Sphinx-Gallery は、ギャラリーディレクトリ内のサブフォルダーのネストを 1 レベルのみサポートしています。例えば、Matplotlib を使用した基本ギャラリー は、親ギャラリーを examples/ に、サブセクション（別名サブギャラリー）を examples/no_output/ に配置しています。それ以上のサブフォルダーはサポートされていません。これは制限事項となる可能性があります。または、例ギャラリーとチュートリアルギャラリーなど、異なる目的で個別のギャラリーを用意したい場合もあります。これを行うには、Sphinx の conf.py ファイルで、Sphinx-Gallery の設定辞書のキー examples_dirs と gallery_dirs をディレクトリのリストとして設定します。

sphinx_gallery_conf = {
    ...
    'examples_dirs': ['../examples', '../tutorials'],
    'gallery_dirs': ['auto_examples', 'tutorials'],
}

両方のリストの長さは同じである必要があることに注意してください。

注記

例の実行に時間がかかる場合は、各ギャラリーディレクトリについて（ビルド中にそのディレクトリで例が実際に実行された限り）、そしてすべてのギャラリーについてグローバルに生成される 実行時間 ファイルを参照することを検討してください。

一致パターンによる例のパースと実行#

デフォルトでは、Sphinx-Gallery は .py 拡張子を持つすべてのファイルをギャラリーにパースして追加しますが、plot_ で始まるファイルのみ実行します。これらの動作は、ignore_pattern、filename_pattern、および example_extensions エントリによって制御され、デフォルト値は次のとおりです。

sphinx_gallery_conf = {
    ...
    'filename_pattern': '/plot_',
    'ignore_pattern': r'__init__\.py',
    'example_extensions': {'.py'}
}

ギャラリーから一部のファイルを完全に省略するには（つまり、実行、パース、追加を行わない）、ignore_pattern オプションを変更します。パースおよび追加された Python スクリプトのうち、実際に実行するものを選択するには、filename_pattern を変更します。例えば

sphinx_gallery_conf = {
    ...
    'filename_pattern': '/plot_compute_',
}

は、plot_compute_ で始まるすべての例をビルドします。filename_pattern（および ignore_pattern）キーは、正規表現 を受け入れ、例のフルパスと照合されます。これが、先頭の '/' が必要な理由です。オペレーティングシステムに依存しないようにするには、'/' の代わりに re.escape(os.sep) を使用することをお勧めします。

filename_pattern オプションは、例の一部のみをビルドする場合にも役立ちます。例えば、ドキュメントにリンクするために 1 つの例のみをビルドする場合があります。その場合は、次のようにします。

sphinx_gallery_conf = {
    ...
    'filename_pattern': r'plot_awesome_example\.py',
}

ここでは、ドット r'\.' をエスケープする必要があります。そうでなければ、Python の 正規表現 は任意の文字と一致します。ただし、特定のファイルを対象としているため、このエスケープ文字がなくてもファイル名内のドットと一致します。

注記

Sphinx-Gallery は、変更された例（それらの MD5 ハッシュに基づいて）のみを再実行します。詳細は、下記の 古い例を再実行する を参照してください。

同様に、特定のディレクトリ内の例のみをビルドするには、次のようにします。

sphinx_gallery_conf = {
    ...
    'filename_pattern': '/directory/plot_',
}

あるいは、例の実行をスキップすることもできます。例えば、plot_long_examples_ で始まる例の実行をスキップするには、次のようにします。

sphinx_gallery_conf = {
    ...
    'filename_pattern': '/plot_(?!long_examples)',
}

パターンは 正規表現 として解析されるため、詳細は 正規表現 モジュールを参照することをお勧めします。

注記

Sphinx はコマンドラインから conf.py の値を上書きできるため、例えば、次のようなコマンドで単一の例を直接ビルドできます。

$ sphinx-build -D sphinx_gallery_conf.filename_pattern=plot_specific_example\.py ...

また、example_extensions に拡張子を追加することで、他の言語の構文例をパースして強調表示することもできますが、それらは実行されません。例えば、Python、Julia、C++ の例を含めるには

sphinx_gallery_conf = {
    ...
    'example_extensions': {'.py', '.jl', '.cpp'}
}

パースと構文の強調表示は Pygments ライブラリによってサポートされており、言語はファイル拡張子によって決定されます。Pygments のデフォルトのファイル関連付けを上書きするには、filetype_parsers オプションを使用して、example_extensions のファイル拡張子のいずれかを pygments の言語名 のいずれかにマッピングする dict を指定できます。例えば

sphinx_gallery_conf = {
    ...
    'filetype_parsers': {'.m': 'Matlab'}
}

古い例を再実行する#

デフォルトでは、Sphinx-Gallery は変更された例のみを再ビルドします。例えば、クリーンな doc/ ディレクトリから開始する場合、HTML ビルドを 1 回実行すると、Sphinx-Gallery は指定された ファイル名/無視パターン に一致するすべての例を実行します。次に、まったく同じコマンドを 2 回目実行しても、例は実行されません。これは、各例の MD5 ハッシュが、最初のビルド時に例ファイルが持っていた MD5 ハッシュ（生成されたディレクトリに <filename>.md5 としてディスクに保存される）と照合されるためです。これらが一致するため、例は「古い」と判断され、Sphinx-Gallery によって再ビルドされません。この設計機能により、例が変更された場合にのみ再ビルドすることで、より迅速なドキュメントの反復が可能になります。

しかし、これはデバッグと反復処理のあるモードで問題を引き起こします。基盤となるライブラリの関数を変更しながら、特定の例を繰り返し再構築したいが、例ファイルの内容自体は変更したくないとします。これを行うには、例に何か変更を加える（例：改行を追加/削除する）か、.md5ファイルを削除してSphinx-Galleryに例の再構築を強制する必要があります。代わりに、次の構成値を使用できます。

sphinx_gallery_conf = = {
    ...
    'run_stale_examples': True,
}

この構成を使用すると、MD5ハッシュで例が変更されていないことが示されていても、ファイル名/無視パターンに一致するすべての例が再構築されます。これはファイル名/無視パターンと組み合わせて、単一の例を繰り返し再実行できます。たとえば、コマンドラインから実行できます。

$ make html SPHINXOPTS="-D sphinx_gallery_conf.run_stale_examples=True -D sphinx_gallery_conf.filename_pattern='my_example_name'"

このコマンドは、ファイル名パターン'my_example_name'に一致するすべての例を、MD5ハッシュに関係なく再構築します。

例スクリプトへのコマンドライン引数の渡#

デフォルトでは、Sphinx-Galleryは例スクリプトにコマンドライン引数を渡しません。reset_argvオプションを設定することで、この動作を変更し、コマンドライン引数を例スクリプトに渡すことができます。reset_argvは、gallery_confとscript_varsの辞書を入力として受け取り、インタープリターに追加のコマンドライン引数として渡される文字列のリストを返すCallableである必要があります。

reset_argvの例を以下に示します。

from pathlib import Path

def reset_argv(sphinx_gallery_conf, script_vars):
    src_file = Path(script_vars['src_file']).name
    if src_file == 'example1.py':
        return ['-a', '1']
    elif src_file == 'example2.py':
        return ['-a', '2']
    else:
        return []

この関数はdoc/sphinxext.pyで定義されており、インポート可能であることを確認しました（Callableのインポートを参照）。

これは、構成辞書に次のように含めることができます。

sphinx_gallery_conf = {
    ...
    'reset_argv': "sphinxext.reset_argv",
}

これはSphinx-Galleryによってreset_argvのcallableに解決され、次のように使用されます。

import sys
sys.argv[0] = script_vars['src_file']
sys.argv[1:] = reset_argv(gallery_conf, script_vars)

注記

下位互換性のために、構成をcallableオブジェクトとして設定することもできますが、__repr__が実行間で安定していることを確認する必要があります。安定した__repr__の確保を参照してください。

カスタムソートキー#

次の構成に対してカスタムソートキーcallableを作成できます。

これを行う最良の方法は、渡されたパス文字列を受け取るソート関数を定義することです。

def plotted_sorter(fname):
    return not fname.startswith("plot_"), fname

インポート可能であることを確認し（Callableのインポートを参照）、構成を設定します。

sphinx_gallery_conf = {
#...,
"minigallery_sort_order": "sphinxext.plotted_sorter",
#...
}

下位互換性のために、構成をcallableオブジェクトとして設定することもできますが、__repr__が実行間で安定していることを確認する必要があります。詳細については、安定した__repr__の確保を参照してください。

__repr__が実行間で安定することを保証するため、sphinx_gallery.sorting.FunctionSortKeyの使用をお勧めします。

sphinx_gallery.sorting.FunctionSortKeyは、初期化時に関数を受け取ります。ソートキー関数を使用してFunctionSortKeyインスタンスをインスタンス化することで、カスタムソートキーcallableを作成できます。たとえば、次のminigallery_sort_order構成（パスでソートする）は、各ファイル名の最初の10文字を使用してソートします。

sphinx_gallery_conf = {
#...,
"minigallery_sort_order": FunctionSortKey(
    lambda filename: filename[:10]),
#...
}

ミニギャラリーの追加#

Sphinx-Galleryは、sphinx_gallery.directives.MiniGalleryディレクティブを提供するため、Sphinxドキュメント.rstファイルにギャラリーの縮小版を簡単に追加できます。そのため、minigalleryディレクティブは、以下のいずれかのリスト（スペース区切り）を渡すことをサポートしています。

オブジェクト名を使用するには、逆参照の生成を有効にする必要があります。詳細については、APIドキュメントへのミニギャラリーの追加を参照してください。逆参照の生成が有効になっていない場合、MiniGalleryディレクティブへのオブジェクトエントリは無視され、すべてのエントリはパスのような文字列またはglobスタイルのパスのような文字列として扱われます。ファイルパスを使用したミニギャラリーの作成で詳細を確認してください。

APIドキュメントへのミニギャラリーの追加#

Sphinx-Galleryは、指定されたモジュールからのオブジェクトのミニギャラリーを生成できます。これは、次のいずれかの例で構成されます。

  1. コード内で関数/メソッド/属性/オブジェクトを使用するか、クラスをインスタンス化します（*暗黙的な逆参照*と呼ばれます）。または

  2. テキストブロックでsphinxマークアップ:func: / :meth: / :attr: / :obj: / :class:を使用して、その関数/メソッド/属性/オブジェクト/クラスを参照します。conf.pyでdefault_roleをこれらの役割のいずれかに設定している場合は、この役割マークアップを省略できます（*明示的な逆参照*と呼ばれます）。

これにより、オブジェクト（関数、メソッド、属性、クラスなど）の完全修飾名をminigalleryディレクティブに渡して、そのオブジェクトに関連するすべての例のminigalleryを追加できます。これは、APIドキュメントで役立ちます。

**暗黙的な逆参照**は、コード内で使用されるオブジェクトと、明示的にインスタンス化されるクラスを自動的に文書化するのに役立ちます。コードでオブジェクトが使用されているすべての例は、*暗黙的に*逆参照として追加されます。**明示的な逆参照**は、例のテキストで*明示的に*参照されているオブジェクト用です。これらは、通常はコード内で暗黙的に返されるのではなく、明示的にインスタンス化されるクラス（例：matplotlib.axes.Axes（これは、ほとんどの場合、関数呼び出し内でのみ間接的にインスタンス化されます））に役立ちます。

たとえば、numpy.expを使用または参照するすべての例を含む小さなギャラリーを埋め込むことができます。これは次のようになります。

numpy.expを使用する例#

指数関数のプロット

指数関数のプロット

サムネイル図の選択

サムネイル図の選択

スクリプト内の関数名の識別

スクリプト内の関数名の識別

このような動作を利用するには、Sphinx-Galleryの設定conf.pyファイルで次のようにアクティブ化する必要があります。

sphinx_gallery_conf = {
    ...
    # directory where function/class granular galleries are stored
    'backreferences_dir'  : 'gen_modules/backreferences',

    # Modules for which function/class level galleries are created. In
    # this case sphinx_gallery and numpy in a tuple of strings.
    'doc_module'          : ('sphinx_gallery', 'numpy'),

    # Regexes to match objects to exclude from implicit backreferences.
    # The default option is an empty set, i.e. exclude nothing.
    # To exclude everything, use: '.*'
    'exclude_implicit_doc': {r'pyplot\.show'},
}

backreferences_dirで指定したパス（ここではgen_modules/backreferencesを選択します）には、' .examples 'で終わる名前のReStructuredTextファイルが作成されます。各.rstファイルには、すべての例で使用され、doc_moduleにリストされているモジュールに属するすべての関数/クラスに固有のギャラリーの縮小版が含まれます。逆参照ファイルは、すべてのオブジェクトに対して生成されます。どの例でも使用されていないオブジェクトには、autodocの解析中に包含エラーを防ぐために空のファイルが作成されます。

backreferences_dirは、conf.pyファイルに対する**相対的な**文字列またはpathlib.Pathオブジェクト、またはNoneである必要があります。デフォルトではNoneです。

場合によっては、Matplotlibのpyplot.showやpyplot.subplots関数など、特定のモジュールについて事実上すべての例で使用されている関数があり、多くの場合、無関係な例がこれらの関数にリンクされます。これを防ぐために、exclude_implicit_docに正規表現として含めることで、特定のオブジェクトの暗黙的な逆参照を除外できます。次の設定では、暗黙的な逆参照がすべて除外されるため、例ギャラリーは、ドキュメントブロックでSphinxマークアップによって明示的に言及されたオブジェクトに対してのみ作成されます。{'.*'}。上記で言及した関数を除外するには、{r'pyplot\.show', r'pyplot\.subplots'}を使用します（ドットではなく任意の文字に一致させるためのエスケープに注意してください。名前があいまいでない場合は、pyplot.showまたは単にshowと書くこともできます）。

ファイルパスを使用したミニギャラリーの作成#

共通の関数を持たないファイル（たとえば、一連のチュートリアル）を使用して、mini-galleryを明示的に作成したい場合があります。そのため、minigalleryディレクティブは、次のものの受け渡しをサポートしています。

  • sphinxギャラリーの例ファイルへのパスのような文字列（conf.pyを基準とする）

  • Sphinx-Galleryの例ファイルへのglobスタイルのパスのような文字列（conf.pyを基準とする）

たとえば、以下のrstは、特定の関数numpy.exp、例examples/plot_sin_.py、および文字列/examples/plot_4*に一致するすべてのファイルを使用するすべての例に関するギャラリーの縮小版を追加します。

.. minigallery::
    :add-heading:

    numpy.exp
    ../examples/plot_0_sin.py
    ../examples/plot_4*

複数の項目をリストすると、すべての例が単一のミニギャラリーにマージされます。ミニギャラリーは、ファイルが存在する場合、または項目が実際に例で使用または参照されている場合にのみ表示されます。サムネイルは、複数のオブジェクト名またはオブジェクト名とファイル/glob入力に対応する場合にも重複する可能性があります。

複数のオブジェクトのいずれかを使用する例#

導入例 - sinのプロット

導入例 - sinのプロット

サムネイル図の選択

サムネイル図の選択

サムネイル画像の図の提供

サムネイル画像の図の提供

指数関数のプロット

指数関数のプロット

サムネイル図の選択

サムネイル図の選択

スクリプト内の関数名の識別

スクリプト内の関数名の識別

ディレクティブの本文に項目のリストを提供することもできます。

.. minigallery::
    :add-heading:

    numpy.exp
    ../examples/plot_0_sin.py
    ../examples/plot_4*

add-headingオプションは、ミニギャラリーの見出しを追加します。文字列引数が提供されない場合、単一の項目のみがリストされている場合、デフォルトの見出しは

「{完全修飾オブジェクト名}を使用する例」

複数の項目を含むギャラリーの場合は、カスタムの見出しメッセージを指定することをお勧めします。それ以外の場合は、デフォルトのメッセージは

「複数のオブジェクトのいずれかの例」

上記で示した例のミニギャラリーは、デフォルトの見出しレベル^を使用しています。これは、heading-levelオプションを使用して変更できます。このオプションは、単一の文字（例：-）を受け入れます。

minigalleryディレクティブへの入力は、スペースで区切られた引数のリストとして渡すこともできます。

.. minigallery:: numpy.exp ../examples/plot_0_sin.py ../examples/plot_4*

グローバル変数の検査の切り替え#

デフォルトでは、Sphinx-Galleryは各コードブロックの最後にグローバル変数（およびコードオブジェクト）を検査して、変数とメソッド呼び出しのクラスを見つけようとします。また、クラスで呼び出されたメソッドも検索しようとします。たとえば、このコード

lst = [1, 2]
fig, ax = plt.subplots()
ax.plot(lst)

は、（インタースフィンクスが正しく設定されていると仮定して）次のリンクで終わるはずです。

ただし、この機能はすべてのインスタンスで正常に機能するとは限りません。さらに、同じスクリプト内で異なるクラスを参照するために変数名が再利用されると、機能しなくなります。

このグローバル変数のイントロスペクションを無効にするには、構成キーを使用できます。

sphinx_gallery_conf = {
    ...
    'inspect_global_variables'  : False,
}

カスタムデフォルトサムネイルの使用#

プロットを生成しない例のサムネイルに独自の画像を使用する場合は、Sphinxのconf.pyファイルを編集して指定できます。default_thumb_fileというキーを構成辞書に追加する必要があります。例:

sphinx_gallery_conf = {
    ...
    'default_thumb_file': 'path/to/thumb/file.png',
}

例への行番号の追加#

グローバルline_numbers設定を追加することで、リストに表示される行番号。

sphinx_gallery_conf = {
    ...
    'line_numbers': True,
}

または、例スクリプトにコメントを追加することで、グローバル設定を上書きできます。

# sphinx_gallery_line_numbers = True

設定コメントの削除#

一部の設定は、# sphinx_gallery_config [= value]というパターンを持つ特別なコメントを例のソースファイルに追加することで、ファイル内で指定できます。デフォルトでは、ソースファイルはそのまま解析されるため、コメントは例に表示されます。

レンダリングされた例からコメントを削除するには、オプションを設定します。

sphinx_gallery_conf = {
    ...
    'remove_config_comments': True,
}

これにより、テキストブロックではなくコードブロックからの設定コメントのみが削除されます。ただし、技術的には、ファイルレベルの設定コメントは、コードブロックとテキストブロックのどちらに配置しても機能します。

独自の最初のノートブックセルと最後のノートブックセルの追加#

Sphinx-Galleryを使用すると、生成されたすべてのノートブックに独自の最初のセルと/または最後のセルを追加できます。最初のセルを追加すると、ノートブックで適切に実行するために必要なコードを含めることができますが、.pyファイルには含めることができません。デフォルトでは、最初のセルは追加されません。

最後のセルを追加すると、ユーザーの環境に関するレポートなど、必要なアクションを実行するのに役立ちます。デフォルトでは、最後のセルは追加されません。

first_notebook_cellとlast_notebook_cell構成パラメーターを変更することで、好きなテキストを選択できます。たとえば、次の最初のセルを追加できます。

# This cell is added by Sphinx-Gallery
# It can be customized to whatever you like

これは、次の構成によって実現されます。

sphinx_gallery_conf = {
    ...
    'first_notebook_cell': ("# This cell is added by Sphinx-Gallery\n"
                            "# It can be customized to whatever you like\n"
                            )
}

last_notebook_cellパラメーターを設定することで、同様に最後のセルを追加できます。

sphinx_gallery_conf = {
    ...
    'first_notebook_cell': ("# This cell is added by Sphinx-Gallery\n"
                            "# It can be customized to whatever you like\n"
                            ),
    'last_notebook_cell': "# This is the last cell",
}

first_notebook_cellまたはlast_notebook_cellの値がNoneに設定されている場合、ノートブックに追加の最初のセルまたは最後のセルは追加されません。

ノートブックへの画像の追加#

ノートブックが生成される場合、デフォルトでは(notebook_images = False) reSTドキュメントブロックのimageディレクティブの画像パス（コードから生成された画像ではない）は、元のパスを使用してマークダウンに含まれます。これには、ローカルファイルシステムに存在するはずの画像へのパスが含まれますが、これはノートブックをダウンロードするユーザーには当てはまりません。

notebook_images = Trueを設定すると、Base64でエンコードされたdata URIを介して、生成されたノートブックに画像が埋め込まれます。data URIを介した画像の包含は、ノートブックのサイズを大幅に増加させる可能性があるため、ギャラリー全体で小さな画像を使用する場合にのみ使用することをお勧めします。

別の方法として、画像に使用されるプレフィックス文字列（ドキュメントがホストされているルートURLなど）を提供することもできます。たとえば、次の構成

sphinx_gallery_conf = {
    ...
    'examples_dirs': ['../examples'],
    'gallery_dirs': ['auto_examples'],
    ...
    'notebook_images': 'https://project.example.com/en/latest/',
    ...
}

reSTドキュメントブロックにimageディレクティブの例があるとします。

.. image:: ../_static/example.jpg
    :alt: An example image

画像は、ソースURLhttps://project.example.com/en/latest/_static/example.jpgを指して生成されたノートブックに追加されます。上記のreST例における画像パスは相対パスであるため、URLにはauto_examplesが含まれていません。../はドキュメントソースディレクトリまで1つ上のディレクトリに移動しました。相対パスと絶対パス（ソースディレクトリから）の両方がサポートされています。したがって、上記の例では/_static/example.jpgと同じURLが生成されます。

プレフィックスは直接適用されるため、必要な場合はプレフィックスに末尾の/を含める必要があります。

ヒント

ホストされたサービスでドキュメントの複数のバージョンを作成し、プレフィックスを使用する場合は、sphinx build -Dコマンドラインオプションを使用して、リンクが正しいバージョンを指していることを確認することを検討してください。例:

sphinx-build \
    -b html \
    -D sphinx_gallery_conf.notebook_images="https://project.example.com/docs/${VERSION}/" \
    source_dir build_dir

pypandocを用いたreSTからMarkdownへの変換#

Sphinx-Galleryは、（インストールされている場合）pypandoc を使用して、各例について生成されるIPythonノートブック（.ipynbファイル）のために、reSTテキストブロックをMarkdownに変換できます。これらは、生の.pyバージョンと共に、各例の最後にダウンロードできます。

Sphinx-GalleryのreSTからMarkdownへのコンバーターは、より複雑なreST構文のサポートが限られています。例がより複雑なreSTを使用している場合、pypandocの方が良い結果が得られる可能性があります。デフォルトでは、「pypandoc」設定はFalseに設定されており、pypandocは使用されません。

pypandocを使用するには、次のように設定します。

sphinx_gallery_conf = {
    ...
    'pypandoc': True,
}

pypandoc.convert_text()パラメータのextra_argsとfiltersを使用して、pandocオプションを使用することもできます。これらのパラメータを使用するには、「pypandoc」設定をキーワード引数の辞書に設定します。

sphinx_gallery_conf = {
    ...
    'pypandoc': {'extra_args': ['--mathjax',],
                 'filters': ['pandoc-citeproc',],
}

警告

特定のpandocオプションは、望ましくない影響を与える可能性があります。注意して使用してください。

JUnit XMLファイルの使用#

Sphinx-Galleryは、例のランタイム、成功、失敗のJUnit XMLファイルを作成できます。たとえば、junit-result.xmlという名前のファイルを/build出力ディレクトリに作成するには、設定キー（パスはHTML出力ディレクトリからの相対パスです）を設定します。

sphinx_gallery_conf = {
    ...
    'junit': '../test-results/sphinx-gallery/junit.xml',
}

デフォルトでは、JUnit XMLファイルの生成は無効になっています（'junit': ''に設定）。JUnit XMLファイルは、CircleCIビルドなどで役立ちます。CircleCI GUIで例のランタイムのサマリーを取得するために、次のような行を追加できます（これはファイルパスdoc/_build/test-results/sphinx-gallery/junit.xmlを解析し、ネストされたサブディレクトリ名に基づいてテストがsphinx-galleryから来たことを推測します）。

- store_test_results:
    path: doc/_build/test-results
- store_artifacts:
    path: doc/_build/test-results

CircleCIとの統合の詳細については、関連するCircleCIドキュメントとブログ投稿を参照してください。

ログレベルの設定#

Sphinx-Galleryは、いくつかの段階でログ出力を記録します。ケース感度が必要なコード（例：plt.subplotとplt.Subplot）について、ケース感度のある名前付けをサポートしないファイルシステム（例：Windows）でドキュメントをビルドする場合、警告が生成される可能性があります。この場合、デフォルトではlogger.warningが出力され、-Wを使用してビルドするとビルドエラーが発生します。ログレベルは次のように設定できます。

sphinx_gallery_conf = {
    ...
    'log_level': {'backreference_missing': 'warning'},
}

現在有効なキーはbackreference_missingのみです。有効な値は'debug'、'info'、'warning'、および'error'です。

すべてのスクリプトのダウンロードボタンの無効化#

デフォルトでは、Sphinx-Galleryは各ギャラリーからすべてのPythonスクリプトとすべてのJupyterノートブックを収集し、zipファイルにして、各ギャラリーの最後にダウンロードできるようにします。この動作を無効にするには、conf.pyファイルの設定辞書に次を追加します。

sphinx_gallery_conf = {
    ...
    'download_all_examples': False,
}

サムネイル画像の選択#

複数の図を生成する例の場合、デフォルトの動作では、各例で最初に作成された図がギャラリーに表示されるサムネイル画像として使用されます。サムネイル画像を後で例スクリプトで生成された図に変更するには、例スクリプトにコメントを追加して、サムネイルとして使用したい図の番号を指定します。たとえば、2番目に作成された図をサムネイルとして使用する場合は、次のようにします。

# sphinx_gallery_thumbnail_number = 2

負の数も使用できます。これは、最後の図から数えます。たとえば、-1は、例で最後に作成された図をサムネイルとして使用することを意味します。

# sphinx_gallery_thumbnail_number = -1

デフォルトの動作はsphinx_gallery_thumbnail_number = 1です。サムネイル図の選択で、この機能の例を参照してください。

サムネイル画像用の画像の提供#

任意の画像を例にサムネイル画像として使用できます。サムネイルとして使用する画像を指定するには、例スクリプトにコメントを追加して、目的の画像へのパスを指定します。画像へのパスはconf.pyファイルからの相対パスにする必要があり、コメントはdocstringの下（できればコードブロック内、設定コメントの削除を参照）にする必要があります。

たとえば、次の例では、_static/フォルダー内のdemo.pngという画像を使用してサムネイルを作成することを定義しています。

# sphinx_gallery_thumbnail_path = '_static/demo.png'

sphinx_gallery_thumbnail_numberはsphinx_gallery_thumbnail_pathよりも優先されます。サムネイル画像用の図の提供で、この機能の例を参照してください。

失敗した例におけるサムネイル動作の制御#

デフォルトでは、予期される失敗した例には、「BROKEN」という単語がスタンプされたサムネイル画像が表示されます。この動作はsphinx_gallery_failing_thumbnailによって制御され、デフォルトではTrueです。サムネイル画像を制御したい場合は、これをFalseに設定します。これにより、サムネイルの動作が「通常」に戻り、サムネイルは最初に作成された図（図が作成されていない場合はデフォルトのサムネイル）または指定されたサムネイルになります。

# sphinx_gallery_failing_thumbnail = False

実行に失敗した例（通常のサムネイル動作の場合）（オプションがFalseの場合）と実行に失敗した例（オプションがデフォルトのTrueの場合）のサムネイルを比較して、この機能の例を参照してください。

Notebookでセルマジックを実行可能にする#

多くの場合、チュートリアルには、ユーザーがターミナルにコピー＆ペーストするbashコードが含まれています。このコードは、ドキュメントを作成する際に実行する必要はありません。なぜなら、環境に既にそれらの依存関係があるからです。そのため、通常はテキスト内のコードブロックとして記述されます。

#%%
# Installing dependencies
#
#     .. code-block:: bash
#
#       pip install -q tensorflow
#       apt-get -qq install curl

これは.pyファイルと.htmlファイルでは問題ありませんが、Jupyter Notebookとしてレンダリングすると問題が発生します。ダウンロードされた.ipynbファイルにはそれらの依存関係がインストールされておらず、bashコードを実行しないと動作しません。

これを修正するために、conf.pyでpromote_jupyter_magicフラグを設定できます。

sphinx_gallery_conf = {
    ...
    'promote_jupyter_magic': True,
}

このフラグがTrueの場合、Jupyter Notebookの作成時に、Jupyterセルマジック（例: %%bashまたは%%writefile）で始まるコードブロックは、実行可能なコードブロックに変換されます。

前の例では、Markdownテキストを次のように変更できます。

#%%
# Installing dependencies
#
#     .. code-block:: bash
#
#       %%bash
#       pip install -q tensorflow
#       apt-get -qq install curl

つまり、TensorFlowとCurlはJupyter Notebookの実行時に自動的にインストールされます。これは、上記のセルマジックだけでなく、すべてのセルマジックで機能し、Jupyter Notebookの作成のみに影響します。

警告

.pyファイルと.htmlファイルが.ipynbファイルとできるだけ一致するようにすることがベストプラクティスです。この機能は、関連するコードをエンドユーザーが実行することを意図している場合にのみ使用する必要があります。

サンプルを実行せずにビルドする#

Sphinx-Galleryは、すべてのサンプルを解析してギャラリーを作成できますが、スクリプトを実行する必要はありません。これは、ギャラリーの速度の可視化プロセスや、ウェブサイトに表示されるサイズ、その他考えられる用途のためだけです。これを実現するには、Makefileを変更してビルドプロセスにno plotオプションを渡す必要があります。

html-noplot:
    $(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
    @echo
    @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

Makefileでは空白が重要であり、インデントはタブでスペースではありません。

あるいは、conf.py内のsphinx_gallery_conf辞書にplot_galleryオプションを追加して、デフォルトとして設定することもできます。

sphinx_gallery_conf = {
    ...
    'plot_gallery': 'False',
}

sphinx-buildコマンドの-Dフラグには常に最高の優先順位が与えられます。

注記

Makefileにhtml-noplotを追加する場合は、Sphinxの設定に関する警告を避けるため、conf.pyファイル内のsphinx_gallery_confディクショナリでplot_galleryのデフォルト値を明示的に設定する必要があります。

画像の圧縮#

PNGファイル（デフォルトのスクレーパー形式）を作成する際、Sphinx-Galleryはoptipngを使用してPNGファイルサイズを最適化するように設定できます。通常、これによりファイルサイズが約50％削減され、ギャラリーの読み込み時間が短縮されます。ただし、ビルド時間が長くなる可能性があります。許可される値は'images'と'thumbnails'、またはタプル/リスト（両方最適化する場合）です。例：

sphinx_gallery_conf = {
    ...
    'compress_images': ('images', 'thumbnails'),
}

デフォルトは()（最適化なし）であり、最適化が要求されているのにoptipngが利用できない場合は警告が表示されます。追加のコマンドラインオプション（'-'で始まる）を渡すこともできます。たとえば、最適化を少なくしてビルド時間を短縮するには、次のようにします。

sphinx_gallery_conf = {
    ...
    'compress_images': ('images', 'thumbnails', '-o1'),
}

オプションの完全なリストについては、$ optipng --helpを参照してください。

マルチ解像度画像#

Webブラウザは、<img>タグにsrcsetパラメータを使用することで、高DPI/Retinaディスプレイ向けの高解像度画像に対応できます。レスポンシブな解像度画像をサポートしています。Sphinx Galleryは、image_srcsetパラメータを使用してこれをサポートしています。

sphinx_gallery_conf = {
    ...
    'image_srcset': ["2x"],
}

これにより、通常の図のdpi（通常は100 dpi）で1xの画像と、2倍の密度（例：200 dpi）で2xのバージョンが保存されます。デフォルトでは追加の画像はなく('image_srcset': [])、必要に応じてリストとして他の解像度を指定できます。["2x", "1.5x"]。

matplotlibスクレーパーは、rstファイルにカスタムイメージディレクティブimage-sgを作成します。

.. image-sg:: /examples/images/sphx_glr_test_001.png
    :alt: test
    :srcset: /examples/images/sphx_glr_test_001.png, /examples/images/sphx_glr_test_001_2_0x.png 2.0x
    :class: sphx-glr-single-img

これは、カスタムディレクティブによって次のようにhtmlに変換されます。

.. <img src="../_images/sphx_glr_test_001.png" alt="test", class="sphx-glr-single-img",
    srcset="../_images/sphx_glr_test_001.png, ../_images/sphx_glr_test_001_2_0x.png 2.0x>

これによりWebサイトは大きくなりますが、srcsetタグをサポートするクライアントは、適切なサイズの画像のみをダウンロードします。

.. image-sgディレクティブは、現在width、height、alignなどの他の.. imageディレクティブタグを無視することに注意してください。また、*html*および*latex*ビルダーでのみ機能します。

画像スクレーパー#

画像スクレーパーは、Sphinx-Galleryが例の実行中に生成された画像を検出し、ドキュメントに埋め込むことを可能にするプラグインです。スクレーパーは、Sphinx-Galleryの設定にある'image_scrapers'タプルにスクレーパー名を追加することで有効にできます。たとえば、matplotlibの画像をスクレイピングするには、次のようにします。

sphinx_gallery_conf = {
    ...
    'image_scrapers': ('matplotlib',),
}

デフォルト値は'image_scrapers': ('matplotlib',)であり、Matplotlib画像のみをスクレイピングします。これには、SeabornやYellowbrickなど、Matplotlibをベースとしたパッケージによって生成された画像も含まれることに注意してください。

Matplotlibアニメーション#

matplotlib.animation.Animationを単一の静止画ではなくアニメーションとして埋め込む場合は、matplotlib_animations設定を使用する必要があります。これは、アニメーションを有効にするかどうかを示すbool値、または(enabled: bool, format: str)形式のタプルを受け入れます。

sphinx_gallery_conf = {
    ...
    'matplotlib_animations': (True, 'mp4'),
}

matplotlib_animationsのデフォルトはFalseです。

Matplotlibでサポートされているアニメーションのファイル形式であればどれでも使用できます。形式が指定されていない場合（つまり、単一のbool値の場合）、または*None*の場合、形式はrcParams['animation.html']およびmatplotlib rcParams内の関連オプションによって決定されます。これは、コードブロック内で設定できることを意味しますが、Sphinx-Galleryは各例ファイルの実行前にMatplotlibのデフォルト値をリセットすることに注意してください（モジュールのリセットを参照）。

形式が'html5'または'jshtml'の場合、アニメーションは結果のHTMLファイルに効果的に埋め込まれます。それ以外の場合は、アニメーションは外部ファイルに保存されるため、生成されるReSTファイルのサイズが小さくなります。外部ファイルに保存する形式を要求する場合は、環境にsphinxcontrib-video拡張機能をインストールする必要があります。

matplotlib_animationsを使用してrcParams['animation.html']をグローバルに設定できますが、コードブロック内で設定すると、グローバル設定が上書きされることに注意してください。

また、「FFmpeg」または「imagemagick」がwriterとして使用できることを確認することをお勧めします。matplotlib.animation.ImageMagickWriter.isAvailable()またはmatplotlib.animation.FFMpegWriter.isAvailable()を使用して確認できます。Matplotlib <3.3.1を使用していない限り、FFMpegライターをお勧めします。

サポートされているスクレーパーは以下のとおりです。

  • matplotlib

    Sphinx-Galleryは、文字列'matplotlib'を介してmatplotlib図のスクレーパーを維持しています。

  • PyVista

    PyVistaは、文字列'pyvista'によって有効化されるスクレーパー（PyVista ≥ 0.20.3の場合）を維持しています。

  • PyGMT

    Sphinx-Galleryとの統合方法の詳細については、ウェブサイトを参照してください。

  • qtgallery

    このライブラリは、Qtウィンドウのスクレーパーを提供します。Sphinx-Galleryとの統合方法については、リポジトリを参照してください。

上記以外のライブラリによって生成された画像のカスタムスクレーパーを作成できます。これは、任意のパッケージによって生成された画像を検出して取得する方法を定義する独自のPython関数を記述することで実現できます。手順については、カスタム画像スクレーパーの作成を参照してください。一般的に有用な実装（たとえば、プロットライブラリのカスタムスクレーパー）を考案した場合は、上記のリストに追加してください（こちらのディスカッションを参照）。

単一の図を作成するための複数のコードブロックの使用#

デフォルトでは、画像は例の各コードブロックの後にスクレイピングされます。したがって、以下は、コードブロックごとに1つのプロットを持つ2つのプロットを生成します。

# %%
# This first code block produces a plot with two lines

import matplotlib.pyplot as plt
plt.plot([1, 0])
plt.plot([0, 1])

# %%
# This second code block produces a plot with one line

plt.plot([2, 2])
plt.show()

ただし、特に図が多数のコマンドを必要とする場合、テキストブロックとインターリーブする方が有利な場合、単一の図を作成するために複数のコードブロックを使用することが有用な場合があります。オプションのフラグsphinx_gallery_defer_figuresをコードブロックの任意の場所にコメントとして挿入して、画像のスクレイピングを次のコードブロックに延期できます（必要に応じてさらに延期できます）。以下は、プロットを1つだけ生成します。

# %%
# This first code block does not produce any plot

import matplotlib.pyplot as plt
plt.plot([1, 0])
plt.plot([0, 1])
# sphinx_gallery_defer_figures

# %%
# This second code block produces a plot with three lines

plt.plot([2, 2])
plt.show()

同じコードブロックからの複数の図のレイアウトの制御#

デフォルトでは、同じコードブロックから生成された複数の図は並べて配置されます。特に幅の広い図の場合、画像が大幅に縮小され、可読性が低下する可能性があります。この動作は、次の2つのオプション変数を使用して制御できます。

  • ファイル全体のsphinx_gallery_multi_image変数

  • コードブロック固有のsphinx_gallery_multi_image_block変数

デフォルトの動作では、これらの変数は"multi"に設定され、図が並べて配置されます。これらの変数を"single"に設定すると、コードブロックから生成された図を単一列で表示できます。

たとえば、次を追加すると

# sphinx_gallery_multi_image = "single"

例ファイル内のどこかに、複数の図が生成されるすべてのコードブロックの画像が単一列で表示されます。

または、次をコードブロックに追加すると

# sphinx_gallery_multi_image_block = "single"

そのコードブロックからの複数の図のみが単一列で表示されます。

逆に、ファイル全体に対してsphinx_gallery_multi_image = "single"が設定されている場合、sphinx_gallery_multi_image_block = "multi"を追加することで、単一コードブロックに対するデフォルトの動作を復元できます。

この機能のデモについては、例プロットを別々の行に表示するように強制するを参照してください。

コード行の非表示#

通常、Sphinx-Galleryは、HTMLとiPython Notebookをビルドする際に、Pythonコードのすべての行をレンダリングします。Pythonソースファイル、HTML、iPython Notebookがすべて同じ動作をするようにしたいので、これは通常望ましいことです。

ただし、実行されるが、ユーザー向けのドキュメントには含まれないPythonコードを使用する場合もあります。たとえば、ドキュメントが正常にビルドされたことを確認するためにいくつかのassert文を追加したいが、ユーザーにこれらを表示したくないとします。sphinx_gallery_start_ignoreとsphinx_gallery_end_ignoreフラグを使用して、これを実現できます。

model.compile()
# sphinx_gallery_start_ignore
assert len(model.layers) == 5
assert model.count_params() == 219058
# sphinx_gallery_end_ignore
model.fit()

HTMLまたはiPython Notebookがビルドされると、このコードブロックは次のように表示されます。

model.compile()
model.fit()

sphinx_gallery_start_ignoreとsphinx_gallery_end_ignoreフラグは、任意のコードブロックで使用でき、同じブロック内で複数のフラグのペアを使用できます。すべての開始フラグには常に対応する終了フラグが必要です。そうでない場合、ドキュメント生成中にエラーが発生します。これらのフラグとその間のコードは、remove_config_commentsの設定に関係なく、常に削除されます。

無視されたコードからの出力は、引き続きキャプチャされることに注意してください。

警告

このフラグは控えめに使用する必要があります。なぜなら、これにより、.pyソースファイルと生成された.htmlファイルと.ipynbファイルの同等性が低くなるためです。この関係を維持できる他の方法がある場合は、これを使用するのは適切な方法ではありません。

ダミー画像の生成#

特に記述プロセス中にギャラリーを迅速に視覚化するために、Sphinx-Galleryでは、コードを実行せずにギャラリーをビルドできます（実行せずにビルドするとファイル名/無視パターンを参照）。ただし、自動生成された画像へのリンクを手動で記述している場合、画像ファイルが見つからないという警告が表示される可能性があります。これらの警告を防ぐには、Sphinx-Galleryに、例の数だけのダミー画像を作成するように指示できます。

たとえば、「my_example.py」という例で2つの図を生成し、それらを他の場所で手動で参照する場合があります。例：

Below is a great figure:

.. figure:: ../auto_examples/images/sphx_glr_my_example_001.png

Here is another one:

.. figure:: ../auto_examples/images/sphx_glr_my_example_002.png

実行せずにビルドする際に、画像ファイルが見つからないという警告を防ぐには、次の例ファイルをに追加します。

# sphinx_gallery_dummy_images=2

これにより、Sphinx-Galleryは、実行してビルドしたときに生成される画像と同じ命名規則と保存場所を使用して、2つのダミー画像を生成します。既存の画像がある場合（たとえば、ビルドの以前の実行からの場合）、ダミー画像は生成されないため、上書きされません。

注記

この設定は、例の実行が設定されていない場合（つまり、plot_galleryが'False'である場合、例がignore_patternに含まれている場合、または例がfilename_patternに含まれていない場合 - ファイル名/無視パターンを参照）にのみ機能します。つまり、ギャラリーを実行してビルドする場合に、例からsphinx_gallery_dummy_images行を削除する必要はありません。

モジュールのリセット#

多くの場合、1つの例でプロットの動作に加えられた変更が他の例に伝播しないようにするために、可視化パッケージの動作を「リセット」したいことがあります。

デフォルトでは、各例ファイルの実行前に、Sphinx-Galleryはmatplotlib（matplotlib.pyplot.rcdefaults()を使用して、ユニットレジストリを設定するサブモジュールを再ロードする）とseaborn（sys.modulesからモジュールをアンロードしようとする）をリセットします。これは、次の設定と同じです。

sphinx_gallery_conf = {
    ...
    'reset_modules': ('matplotlib', 'seaborn'),
}

現在、Sphinx-Galleryはmatplotlibとseabornのリセットをネイティブにサポートしています。ただし、このタプルに独自の関数を追加して、他の可視化ライブラリの動作のリセットを定義することもできます。

これを行うには、各例の前に行うリセットの手順に従ってください。

モジュールのリセットの順序#

デフォルトでは、Sphinx-Galleryは各例の実行前にモジュールをリセットします。reset_modules_orderの選択肢はbefore（デフォルト）、after、およびbothです。Sphinx-Galleryで実行された最後の例がモジュールを変更した場合、変更されたモジュールがSphinxのビルドプロセスの他の部分に漏れるのを防ぐために、afterまたはbothを使用することをお勧めします。たとえば、設定でreset_modules_orderをbothに設定します。

sphinx_gallery_conf = {
    ...
    'reset_modules_order': 'both',
}

例の前または後に呼び出されるかどうかに応じて、独自の機能を持つカスタム関数を構築できます。各例の前に行うリセットで詳細情報を確認してください。

サンプル推奨システムの有効化#

Sphinx-Galleryは、サンプルギャラリーのコンテンツベースの推奨事項を生成するように構成できます。関連するサンプルのリストは、テキストコンテンツのTF-IDF空間で最も近いサンプルを計算することによって自動的に生成されます。最も近いサンプルの計算には、単一のギャラリー（そのサブギャラリーを含む）内のサンプルのみが使用されます。次に、最も類似したコンテンツが、サムネイルのセットとして各サンプルの最後に表示されます。

enableをTrueに設定することで、推奨システムを有効にできます。設定するには、sphinx_gallery_confに辞書を渡します。

sphinx_gallery_conf = {
    ...
    "recommender": {"enable": True, "n_examples": 5, "min_df": 3, "max_df": 0.9},
}

必要なパラメーターはenableのみです。他のパラメーターが指定されていない場合、デフォルト値が使用されます。以下は、各フィールドのより詳細な説明です。

enable （型：bool、デフォルト：False）

サンプルギャラリー内で推奨事項を生成するかどうか。この機能を有効にするには、依存関係にnumpyを追加する必要があります。

n_examples （型：int、デフォルト：5）

表示する最も関連性の高いサンプルの数。

min_df （型：[0.0, 1.0]の範囲のfloat | int、デフォルト：3）

語彙を作成する際に、指定されたしきい値よりも厳密に低い文書頻度を持つ用語を無視します。floatの場合、パラメーターは文書の割合を表し、整数値は絶対カウントを表します。この値は、文献ではカットオフとも呼ばれます。

max_df （型：[0.0, 1.0]の範囲のfloat | int、デフォルト：0.9）

語彙を作成する際に、指定されたしきい値よりも厳密に高い文書頻度を持つ用語を無視します。floatの場合、パラメーターは文書の割合を表し、整数値は絶対カウントを表します。

rubric_header （型：str、デフォルト：“Related examples”）

カスタマイズ可能なルブリックヘッダー。より説明的なテキストに変更したり、Sphinx-Galleryのドキュメントにある推奨システムのAPIドキュメントへの外部リンクを追加したりできます。

min_dfとmax_dfパラメーターは、非常にまれな単語や非常に一般的な単語をトリミングするためにユーザーがカスタマイズできます。これにより、推奨事項の品質が向上する可能性がありますが、さらに重要なのは、情報のないトークンに無駄になる計算リソースを節約できることです。

現在、サンプルの推奨事項は.pyファイルに対してのみ計算されます。

最小報告時間#

デフォルトでは、Sphinx-Galleryは、各スクリプトの実行にかかった時間をログに記録し、HTML出力に埋め込みます。ほとんどのサンプルが高速に実行される場合、この情報は必要ない可能性があります。

min_reported_timeパラメーターは、秒数に設定できます。その時間よりも速く実行されたスクリプトの継続時間は、ログに記録されず、HTML出力にも埋め込まれません。

計算時間の書き込み#

すべてのギャラリー出力から計算時間を省略する場合は、Falseに設定します。これは、再現可能なビルドに役立ちます。SOURCE_DATE_EPOCH環境変数が設定されていない限り、デフォルトはTrueです。

メモリ消費量の表示#

Sphinx-Galleryは、インストールされている場合、memory_profilerを使用して、サンプルの実行中のピークメモリを報告できます。memory_profilerをインストールした後、次のように実行できます。

sphinx_gallery_conf = {
    ...
    'show_memory': True,
}

GPUメモリなどを表示する必要がある場合など、独自のメモリレポーターを使用することもできます。その場合、show_memoryは、呼び出す単一の関数（つまり、個々のスクリプトコードブロックを実行するために内部で生成されたもの）を受け取り、次の2つの要素のタプルを返すcallableでなければなりません。

  1. 関数の実行中に使用されたメモリ（MiB単位）、および

  2. 関数の出力

常に0のメモリ使用量を報告するバージョンは次のとおりです。

sphinx_gallery_conf = {
    ...
    'show_memory': lambda func: (0., func()),
}

シグネチャの表示#

デフォルトでは、Sphinx-Galleryは生成された出力に**Generated by …**という通知を書き込みます。

show_signatureパラメーターを使用して、これを無効にすることができます。

キャプチャする出力の制御#

注記

バージョンv0.5.0より前の出力キャプチャ動作に戻すには、capture_reprを空のタプル（つまり、capture_repr: ()）に設定します。

capture_repr設定により、サンプルの.pyファイルの実行中にキャプチャする出力を制御し、その後、構築されたドキュメントに組み込むことができます。標準出力に送られたデータは常にキャプチャされます。*各*コードブロックの最後のステートメントの値が式である場合も、キャプチャできます。これを行うには、優先順位に従ってcapture_reprタプルにキャプチャする「表現」メソッドの名前を提供します。現在サポートされている表現メソッドは次のとおりです。

  • __repr__ - オブジェクトの公式な文字列表現を返します。これは、Pythonシェルで式を評価したときに返されるものです。

  • __str__ - オブジェクトの適切に印刷可能な表現を含む文字列を返します。これは、オブジェクトをprint()するとき、またはformat()に渡すときに使用されます。

  • _repr_html_ - オブジェクトのHTMLバージョンを返します。このメソッドは、pandasのデータフレームなどの一部のオブジェクトにのみ存在します。

出力キャプチャは、capture_repr設定でグローバルに制御したり、サンプルファイルにコメントを追加してファイルごとに制御したりできます。これは、グローバル設定を上書きします。

# sphinx_gallery_capture_repr = ()

デフォルトの設定は次のとおりです。

sphinx_gallery_conf = {
    ...
    'capture_repr': ('_repr_html_', '__repr__'),
}

デフォルトの設定では、Sphinx-Galleryはまず、コードブロックの最後のステートメントが式である場合、その_repr_html_のキャプチャを試みます。このメソッドが式に存在しない場合、タプル内の2番目の「表現」メソッドである__repr__がキャプチャされます。__repr__も存在しない場合（ユーザー定義オブジェクト以外ではまれ）、何もキャプチャされません。標準出力に送られたデータは**常に**キャプチャされます。いくつかのサンプルについては、出力表現のキャプチャを参照してください。

標準出力に送られたデータのみをキャプチャするには、'capture_repr'を空のタプルに設定します：'capture_repr': ()。これにより、v0.5.0より前のSphinx-Galleryの動作が模倣されます。

別の視点から見ると、次のコードブロックを考えてみましょう。

print('Hello world')
a=2
a  # this is an expression

'Hello world'は、標準出力に送られるため、すべてのcapture_repr設定でキャプチャされます。さらに、

  • capture_reprが空のタプルである場合、それ以外は何もキャプチャされません。

  • capture_repr が ('__repr__') の場合、2 もキャプチャされます。

  • capture_repr が ('_repr_html_', '__repr__')（デフォルト）の場合、Sphinx-Gallery はまず _repr_html_ のキャプチャを試みます。 a には _repr_html_ が存在しないため、次に __repr__ のキャプチャを試みます。 a には __repr__ メソッドが存在するため、この場合も 2 はキャプチャされます。

Matplotlib に関する注記: 'capture_repr' タプルに '__repr__' および/または '__str__' が含まれている場合、Matplotlib 関数の呼び出しを最後の式とするコードブロックは、一般的に生成されたドキュメントに図と共に黄色の出力ボックスを生成します。これは、Matplotlib 関数の呼び出しは通常、標準出力にプロットを作成/修正するだけでなく、何かを返すためです。たとえば、matplotlib.plot() は、プロットされたデータを表す Line2D オブジェクトのリストを返します。このリストには __repr__ と __str__ メソッドが存在するため、キャプチャされます。これを回避するには、

  • (最後の)プロット関数を一時変数に代入します。例：

    import matplotlib.pyplot as plt

_ = plt.plot([1, 2, 3, 4], [1, 4, 9, 16])

  • plt.show()（何も返さない）をコードブロックの最後に追加します。例：

    import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4], [1, 4, 9, 16])
plt.show()

'capture_repr' が空のタプルである場合、または __repr__ や __str__ を含まない場合、不要な文字列出力は発生しません。

特定のクラスのキャプチャを防止する#

各コードブロックの最後の式の表現をキャプチャしたいが、ただし、最後の式が特定の型である場合は除外したい場合は、'ignore_repr_types' を使用できます。'ignore_repr_types' はデフォルトでは空の raw 文字列（r''）であり、どの型も無視されません。特定の型を除外するには、'ignore_repr_types' を、除外する型の名前と一致する正規表現に設定できます。

たとえば、以下の設定では、最後の式のtype() の名前が文字列 'matplotlib.text' または 'matplotlib.axes' を含む場合を除き、各コードブロックの最後の式の __repr__ がキャプチャされます。これにより、'matplotlib.text' のすべてのサブクラス（例：'matplotlib.text.Annotation'、'matplotlib.text.OffsetFrom' など）のキャプチャが防止されます。同様に、'matplotlib.axes' のサブクラス（例：'matplotlib.axes.Axes'、'matplotlib.axes.Axes.plot' など）もキャプチャされません。

sphinx_gallery_conf = {
    ...
    'capture_repr': ('__repr__'),
    'ignore_repr_types': r'matplotlib\.(text|axes)',
}

ファイルの手動渡し#

デフォルトでは、Sphinx-Gallery は sphinx-build ディレクトリに書き込まれるすべてのファイルを作成します。これは、ギャラリーソースの *.py から rst と画像を生成するか、ギャラリーソースの GALLERY_HEADER.rst（または下位互換性のために README.[rst/txt]）から index.rst を作成することによって行われます。ただし、ギャラリーソースから sphinx-build にファイルを渡すことが望ましい場合があります。たとえば、ギャラリーが参照するが、それ自体では生成しない画像を渡したい場合があります。ギャラリーソースから sphinx-build に raw rst を渡すこともできます。これは、その素材がギャラリーのテーマに合致するが、rst として記述する方が簡単であるためです。これに対応するために、sphinx_gallery_conf で copyfile_regex を設定できます。次の例では、rst ファイルがコピーされます。

sphinx_gallery_conf = {
    ...
   'copyfile_regex': r'.*\.rst',
}

rst ファイルをコピーする場合などは、それらがドキュメント内のどこかの sphinx toctree に含まれていることを確認する責任があります。もちろん、GALLERY_HEADER.rst に toctree を追加することもできます。

index.rst の手動渡し#

ギャラリーディレクトリまたはネストされたサブギャラリーディレクトリ内の GALLERY_HEADER.rst から Sphinx-Gallery が自動的に index.rst を作成することを回避できます。copyfile_regex に index.rst が含まれており、ギャラリーソース（つまり、examples_dirs ディレクトリ）に index.rst がある場合、Sphinx-Gallery は代わりにそれを使い、そのギャラリーまたはそのサブギャラリーのインデックスファイルを作成しません。独自の index.rst ファイルを渡す場合は、そのインデックス（またはSphinxドキュメントの他の場所）に独自のSphinx toctree を追加して、そのディレクトリ内のギャラリーアイテムまたはその他のファイルを含める責任があります。また、そのギャラリーのサブギャラリーに必要な index.rst ファイルを追加する責任もあります。

API 使用状況の表示#

使用されていないAPIエントリとそのAPIエントリが使用されている各例のドキュメントとグラフは、Sphinx出力ディレクトリのsg_api_usage.html下に生成されます。例については、Sphinx-Gallery API使用状況ドキュメントとグラフを参照してください。大規模なプロジェクトでは、多くのモジュールが存在し、各モジュールごとにAPI使用状況のグラフが生成されるため、多くのリソースを使用する可能性があります。そのため、show_api_usageはデフォルトで'unused'に設定されています。使用されていないAPIエントリはすべて1つのグラフに表示されるため、大規模なプロジェクトでもスケーラビリティが向上します。show_api_usageをTrueに設定すると、使用されているAPIエントリが接続されている例をすべて表示するモジュールごとのグラフが作成されます。これは、特定のモジュールについて学習したい場合に、どの例を参照すべきかのマップを作成するのに役立つ場合があります。show_api_usageをFalseに設定すると、API使用状況に関するグラフやドキュメントは作成されません。なお、使用されていないAPIエントリと使用されているAPIエントリのグラフを作成するには、graphvizが必要です。

APIエントリの無視#

デフォルトでは、api_usage_ignore='.*__.*__'は、この正規表現に一致するファイルを無視して、例ギャラリー内のAPIエントリの使用状況の文書化とグラフ化を行います。この正規表現を変更して、考慮すべきではない任意の種類のファイルを無視することができます。デフォルトの正規表現は、例で使用されているかどうかを文書化する必要がない可能性のある__len__()などの関数を無視します。

このページの内容