高度な使用方法#

このページには、Sphinx-Gallery の使用方法をより深く理解したい場合に役立つ、より高度なトピックが含まれています。

警告とエラー出力の理解#

ギャラリーの Python ファイルのコードブロックを実行するときに発生する警告またはエラーは、ドキュメントのビルド中にピンク色で表示されます。エラーが発生した .py ファイルのパスと行番号も表示されます。たとえば、例 実行に失敗する例 は、次のエラーを発生させます。

File "<full_path>/examples/no_output/plot_raise.py", line 27, in <module>
    iae
NameError: name 'iae' is not defined

ギャラリーの Python ファイルのテキスト（reST）ブロックの問題は、Sphinx が生成された .rst ファイルを HTML に変換するときに、警告またはエラーになります。これらは、コードブロックのエラーの後、ドキュメントのビルド中に、Sphinx によってピンク色で表示されます。この場合、.rst ファイルのパスと .rst ファイルの行番号が表示されます。問題を修正するには、生成された .rst ファイルではなく、元の .py ファイルを変更する必要があります。問題が発生した場所を特定するには、表示された行番号で .rst ファイルの内容と元の .py ファイルを照合する必要があります。

例 .rst 警告

<full_path>/auto_examples/plot_example.rst:19: WARNING: Explicit markup ends without a blank line; unexpected unindent.

上記の警告は、plot_example.rst の 19 行目で発生しました。修正するには、元の plot_example.py ファイルを変更する必要があります。Sphinx-Gallery は新規、変更済み、または失敗した例のみを（再）ビルドするため、ドキュメントのビルドを再実行すると、変更された例のみが再ビルドされ、迅速な反復が可能になります。

カスタムイメージスクレイパーの作成#

警告

カスタムスクレイパーのAPIは現在実験段階です。

デフォルトでは、Sphinx-Gallery は Matplotlib のイメージスクレイピングをサポートしています（matplotlib_scraper()）。他の Python パッケージからの出力をキャプチャする場合は、最初に、キャプチャするオブジェクトに _repr_html_ メソッドがあるかどうかを確認してください。ある場合は、構成 capture_repr（キャプチャする出力の制御）を使用して、カスタムスクレイパーを作成する必要なく、オブジェクトの表示を制御できます。この構成により、jupyterなどの他のHTMLベースの表示と同様のプロセスで、生のHTML出力をキャプチャできます。最初のオプションが機能しない場合は、このセクションでカスタムスクレイパーの作成方法について説明します。

イメージスクレイパーは、次のことを行う関数（または呼び出し可能なクラスインスタンス）です。

  1. コードの最新実行で作成された画像のリストを収集します。

  2. これらの画像をPNG、JPEG、SVG、GIF、またはWebP形式でディスクに書き込みます（それぞれ.png、.jpg、.svg、.gif、または.webp拡張子を使用）。

  3. これらの図を構築されたドキュメントに埋め込むreSTを返します。

関数は、次の入力（この順序）を受け取る必要があります。

  1. block - Sphinx-Gallery の .py ファイルは、「コード」と reST「テキスト」の連続する行に分割され、「ブロック」と呼ばれます。各ブロックに対して、「type」、「content」、「lineno」項目を持つ名前付きタプル（例：('code', 'print("Hello world")', 5)）が作成されます。

    • 「label」は、「text」または「code」のいずれかの文字列です。このコンテキストでは、この関数はコードブロックに対してのみ呼び出されるため、「code」のみである必要があります。

    • 「content」は、コードブロックの実際の内容を含む文字列です。

    • 「lineno」は、ブロックが開始する行番号を示す整数です。

  2. block_vars - 構成と実行時の変数の辞書。イメージスクレイパーにとって重要なのは、'image_path_iterator' 要素であり、これはSphinx-Galleryの命名規則に従った画像ファイル名の絶対パスを返す反復可能オブジェクトです。このパスはgallery_dirs/imagesディレクトリを指し（Sphinx-Gallery の構成と使用）、画像ファイル名は'sphx_glr_'に続いてソース.pyファイルの名前、次に1から始まり1ずつ増加する番号が続きます。デフォルトのファイル形式は.'png'です。例：'home/user/Documents/module/auto_examples/images/sphx_glr_plot_mymodule_001.png'。異なる画像拡張子が望まれる場合、スクレイパーはデフォルトの.png拡張子を置き換える責任があります。上記でサポートされている画像拡張子のみが、Sphinx-Gallery でファイルが取得されるようにします。

  3. gallery_conf - Sphinx-Gallery の設定を含む辞書で、doc/conf.py 内の sphinx_gallery_conf の下に設定されます（設定）。特に、image_srcset 設定は、ユーザーが指定した画像解像度（浮動小数点数）を提供し、カスタムスクレイパーで多解像度画像を有効にするために使用できます。

ドキュメントにこの図を埋め込むための reST を含む文字列を返す必要があります。matplotlib_scraper() をスクレイパー関数の例として参照してください（関数名の下の「ソース」をクリックしてソースコードを参照できます）。matplotlib_scraper() は、ヘルパー関数 sphinx_gallery.scrapers.figure_rst() を使用して reST を生成します（下記参照）。

この関数は、サンプルコードの各コードブロックに対して1回呼び出されます。Sphinx-Gallery は、ギャラリーインデックスページのサムネイルの画像のスケーリングを処理します。PNG、JPEG、WebP 画像は Pillow を使用してスケーリングされ、SVG と GIF 画像はコピーされます。

警告

SVG 画像は latex ビルドモードでは機能しないため、ドキュメントの PDF バージョンを作成するときに機能しません。sphinxcontrib-svg2pdfconverter を検討することをお勧めします。

例1：Matplotlib スタイルのスクレイパー#

例として、仮想パッケージのスクレイパーのサンプルコードを示します。これは、sphinx_gallery.scrapers.matplotlib_scraper() が内部で行っている処理と同様のアプローチを使用しており、ヘルパー関数 sphinx_gallery.scrapers.figure_rst() を使用して標準化された reST を作成します。パッケージが画像ファイル（例：PNG または JPEG）をディスクに書き込む場合、同様のアプローチを使用することをお勧めします。

def my_module_scraper(block, block_vars, gallery_conf):
    import mymodule
    # We use a list to collect references to image names
    image_names = list()
    # The `image_path_iterator` is created by Sphinx-Gallery, it will yield
    # a path to a file name that adheres to Sphinx-Gallery naming convention.
    image_path_iterator = block_vars['image_path_iterator']

    # Define a list of our already-created figure objects.
    list_of_my_figures = mymodule.get_figures()

    # Iterate through figure objects, save to disk, and keep track of paths.
    for fig, image_path in zip(list_of_my_figures, image_path_iterator):
        fig.save_png(image_path)
        image_names.append(image_path)

    # Close all references to figures so they aren't used later.
    mymodule.close('all')

    # Use the `figure_rst` helper function to generate the reST for this
    # code block's figures. Alternatively you can define your own reST.
    return figure_rst(image_names, gallery_conf['src_dir'])

このコードは、conf.py ファイル内、または conf.py ファイルにインポートするモジュールとして定義できます（呼び出し可能オブジェクトのインポートを参照）。このスクレイパーを使用するために必要な設定は次のようになります。

sphinx_gallery_conf = {
    ...
    'image_scrapers': ('matplotlib', "my_module._scraper.my_module_scraper"),
}

ここで、Sphinx-Gallery は文字列 "my_module._scraper.my_module_scraper" を解析して、呼び出し可能な関数をインポートします。

例2：ディスク上の画像ファイルの検出#

これは、画像が既にディスクに書き込まれていることを前提とした別の例です。この場合、画像ファイルは生成せず、ドキュメントに埋め込むために必要な reST だけを生成します。ファイルのスクレイピングには、サンプルスクリプトの実行が必要ですが、実行中に画像は生成する必要がないことに注意してください。

関数は、_scraper というモジュール内のパッケージ内で定義されていると仮定します。スクレイパーコードを以下に示します。

from glob import glob
import shutil
import os
from sphinx_gallery.scrapers import figure_rst

def png_scraper(block, block_vars, gallery_conf):
    # Find all PNG files in the directory of this example.
    path_current_example = os.path.dirname(block_vars['src_file'])
    pngs = sorted(glob(os.path.join(path_current_example, '*.png')))

    # Iterate through PNGs, copy them to the Sphinx-Gallery output directory
    image_names = list()
    image_path_iterator = block_vars['image_path_iterator']
    seen = set()
    for png in pngs:
        if png not in seen:
            seen |= set(png)
            this_image_path = image_path_iterator.next()
            image_names.append(this_image_path)
            shutil.move(png, this_image_path)
    # Use the `figure_rst` helper function to generate reST for image files
    return figure_rst(image_names, gallery_conf['src_dir'])

次に、conf.py ファイルに次のコードを含めます。

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

例3：SVG形式のmatplotlib#

sphinx_gallery.scrapers.matplotlib_scraper() は、matplotlib.figure.Figure.savefig() に渡す **kwargs をサポートしており、その1つに format 引数があります。カスタム画像スクレイパーの作成でサポートされている形式を参照してください。SVG を使用するには、次の関数を定義し、インポート可能であることを確認します。

def matplotlib_svg_scraper(*args, **kwargs):
    return matplotlib_scraper(*args, format='svg', **kwargs)

次に、conf.py で

sphinx_gallery_conf = {
    ...
    'image_scrapers': ("sphinxext.matplotlib_svg_scraper",),
    ...
}

画像ごとに異なる形式を使用することもできますが、そのためには、カスタマイズされたスクレイパークラスまたは関数を記述する必要があります。

例4：Mayaviスクレイパー#

従来、Sphinx-Gallery は、matplotlib 図と同様に Mayavi 図のスクレイピングもサポートしていました。ただし、スクレイパーの保守の複雑さから、バージョン 0.12.0 でサポートが廃止されました。Mayavi スクレイピングを引き続き使用するには、次のようなものを使用することを検討してください。

from sphinx_gallery.scrapers import figure_rst

def mayavi_scraper(self, block, block_vars, gallery_conf):
    from mayavi import mlab
    image_path_iterator = block_vars['image_path_iterator']
    image_paths = list()
    e = mlab.get_engine()
    for scene, image_path in zip(e.scenes, image_path_iterator):
        try:
            mlab.savefig(image_path, figure=scene)
        except Exception:
            mlab.close(all=True)
            raise
        # make sure the image is not too large
        scale_image(image_path, image_path, 850, 999)
        if 'images' in gallery_conf['compress_images']:
            optipng(image_path, gallery_conf['compress_images_args'])
        image_paths.append(image_path)
    mlab.close(all=True)
    return figure_rst(image_paths, gallery_conf['src_dir'])

各例の前にリセットする#

Sphinx-Gallery は、各サンプルスクリプトの実行の前後に行われる「リセット」関数（複数可）をサポートしています。これは、Sphinx-Gallery でネイティブに、可視化パッケージ matplotlib と seaborn の動作を「リセット」するために使用されます（モジュールのリセット）。ただし、この機能は他のライブラリのリセット、ネイティブにリセットされるライブラリの動作の変更、または各スクリプトの先頭と末尾で任意のカスタム関数の実行に使用できます。

これは、conf.py で定義されたリセットタプルにカスタム関数を追加することで行われます。関数は、gallery_conf という辞書（Sphinx-Gallery の設定）と fname という文字列（現在実行中の Python スクリプトのファイル名）という2つの変数を取ります。これらの変数は、リセット動作を実行するために一般的に使用される必要はありませんが、互換性の理由から関数定義に含める必要があります。

例として、matplotlib を常に ggplot スタイルを使用するようにリセットするには、次のようにします。

def reset_mpl(gallery_conf, fname):
    from matplotlib import style
    style.use('ggplot')

カスタム関数は、conf.py で定義（またはインポート）して、reset_modules 設定キーに渡すことができます。上記で定義された関数（インポート可能にしたと仮定）を追加するには、

sphinx_gallery_conf = {
    ...
    'reset_modules': ("sphinxext.reset_mpl", "seaborn"),
}

上記の設定では、"seaborn" はネイティブの seaborn リセット関数を参照しています（モジュールのリセットを参照）。

注記

ユーザーが手動でサンプルを実行したときに経験する標準的な動作から逸脱する reset_mpl などのリセッターの使用は、レンダリングされたサンプルとローカル出力との間に一貫性の無さが生じるため、推奨されません。

カスタム関数が、例の前後どちらで実行されているかを認識する必要がある場合、3つのパラメーターを持つ関数シグネチャを使用できます。3番目のパラメーターは when という名前である必要があります。

def reset_mpl(gallery_conf, fname, when):
    import matplotlib as mpl
    mpl.rcParams['lines.linewidth'] = 2
    if when == 'after' and fname=='dashed_lines':
        mpl.rcParams['lines.linestyle'] = '-'

when に渡される値は 'before' または 'after' です。設定の 設定 で reset_modules_order が 'before' または 'after' に設定されている場合、when は常に reset_modules_order の設定値と同じになります。この関数シグネチャは、reset_modules_order が 'both' に設定されている場合にのみ役立ちます。

このページの内容