Sphinx-Gallery入門#

基本的なギャラリーの作成#

このセクションでは、Sphinx拡張機能であるSphinx-Galleryを使用して、例の基本的なギャラリーを設定する方法について説明します。これにより、次のことが行われます。

Sphinx reSTを.pyの例ファイルから自動的に生成します。生成されたreSTのレンダリングにより、ユーザーは各例の.ipynb（Jupyter Notebook）と.pyファイルをダウンロードできます。
これらの例それぞれにサムネイルを含むギャラリーを作成します（scikit-learnが使用しているものなど）。

サンプルの例ギャラリーと基本的な設定を含むテンプレートリポジトリも利用可能です。

注記

sphinx_galleryで動作するsphinxビルダーには、html、dirhtml、latexが含まれます。

プロジェクトファイルとフォルダーの概要#

このセクションでは、Sphinx-Galleryで例を構築するために必要な一般的なファイルと構造について説明します。

Pythonプロジェクトの構造が次のようになっているとします。

.
├── doc
│   ├── conf.py
│   ├── index.rst
|   ├── make.bat
│   └── Makefile
├── my_python_module
│   ├── __init__.py
│   └── mod.py
└── examples
    ├── plot_example.py
    ├── example.py
    └── GALLERY_HEADER.rst (or README.[rst/.txt])

docはSphinxの「ソースディレクトリ」です。Sphinxの基本設定ファイルが含まれています。これらの基本ファイルのデフォルトバージョンは、sphinx-quickstartを実行することで取得できます（詳細はSphinx-quickstartを参照）。Sphinxの.rstソースファイルは通常ここに配置されます（上記の例ディレクトリ構造には含まれていません）が、これらはSphinx-Galleryの機能とは関連付けられていません。
my_python_moduleには、Pythonモジュールの.pyファイルが含まれています。このディレクトリは必須ではなく、Sphinx-Galleryはパッケージの例の文書化以外の様々な目的で使用できます。たとえば、PythonチュートリアルのWebサイトを作成する場合などです。
examplesには、Sphinx-Galleryでギャラリーを構築するために使用されるファイルが含まれています。

Sphinx-Galleryは、examplesディレクトリに特定の構造があることを期待しています。次に説明します。

examplesフォルダーの構造#

Sphinx-Galleryでexamplesフォルダーからギャラリーを構築するには、このフォルダーに次のものが必要です。

**ギャラリーヘッダー**: GALLERY_HEADER.[ext]という名前のファイル。ここで[ext]は「txt」またはsphinx_gallery_conf["source_suffix"]のエントリ（または下位互換性のためにREADME.[ext]）です。デフォルトの推奨事項はGALLERY_HEADER.rstです。このファイルには、ギャラリーのウェルカムページのヘッダーとして使用されるreSTが含まれている必要があります。これには、このフォルダーから生成されたサムネイルも含まれます。少なくともタイトルが必要です。例：
```
This is my gallery
==================

Below is a gallery of examples
```
**Pythonスクリプトの例**: HTMLドキュメントを構築するときに処理されるPythonスクリプトのコレクション。埋め込みreSTを使用してこれらのPythonスクリプトを構成する方法については、Sphinx-GalleryのためのPythonスクリプトの構成を参照してください。
- デフォルトでは、plot_で始まるファイルのみが実行され、その出力がキャプチャされてスクリプトのHTML出力に組み込まれます。接頭辞のないファイルは、出力なしで、リテラルプログラミング形式で解析および表示されます。実行とキャプチャのデフォルトのファイルパターンを変更するには、パターンによる例のパースと実行を参照してください。
- .pyファイルの実行中にキャプチャされ、その後構築されたドキュメントに組み込まれる出力は、細かく調整できます。キャプチャする出力の制御を参照してください。
- examplesディレクトリにサブディレクトリを含めることができます。これらは、ギャラリーのサブセクションとして含まれます。それらには、独自のGALLERY_HEADER.[ext]ファイルも含まれている必要があります。[ext]は「txt」またはsphinx_gallery_conf["source_suffix"]のエントリであることに注意してください。README.[ext]も下位互換性のためにサポートしています。

警告

変数名___（アンダースコア3つ）は、内部的なSphinx-Gallery変数として使用されているため、例となるPythonスクリプトでは決して使用しないでください。

Sphinx-Galleryの設定と使用#

Sphinx-Galleryがインストールされた後、Sphinxでビルドできるように有効化し、設定する必要があります。

まず、Sphinxのdoc/conf.pyファイルでSphinx-Galleryを有効にします。

extensions = [
    ...
    'sphinx_gallery.gen_gallery',
    ]

これにより、Sphinx-Galleryが拡張機能の1つとしてロードされます。...は、他のロードされた拡張機能を表します。

次に、Sphinx-Galleryの設定ディクショナリを作成します。ここでは、最小限必要な設定のみを設定します。「examples」ディレクトリ（ギャラリーヘッダーファイルと例となるPythonスクリプトを含む）の場所と、生成された出力ファイルを配置するディレクトリを設定する必要があります。これらの両方のディレクトリへのパスは、doc/conf.pyファイルからの相対パスである必要があります。

次の設定では、「examples」ディレクトリ('example_dirs')を../examples、「output」ディレクトリ('gallery_dirs')をauto_examplesとして宣言します。

sphinx_gallery_conf = {
     'examples_dirs': '../examples',   # path to your example scripts
     'gallery_dirs': 'auto_examples',  # path to where to save gallery generated output
}

ドキュメントを構築した後、gallery_dirsには次のファイルとディレクトリが含まれます。

index.rst - ギャラリーヘッダー、目次ツリー、各例のサムネイルを含むギャラリーのマスタードキュメント。このギャラリーのウェルカムページとして機能します。
sg_execution_times.rst - すべての例.pyファイルの実行時間（表形式で要約）（GitHubの元のプルリクエスト）。
images - 例.pyファイルの実行中に生成された画像（画像スクレイパーの詳細）、およびギャラリーのサムネイル画像が含まれるディレクトリ。
'example_dirs'内の各サブディレクトリに対応するディレクトリ。各ディレクトリ内には、その「サブギャラリー」（別名サブセクション）の上記のファイルと以下のファイルが含まれます。

さらに、**各**.pyファイルに対して、次の接尾辞を持つファイルが生成されます。

.rst - .pyファイルのレンダリングされたreSTバージョン。Sphinxがビルドする準備ができています。
.ipynb - ユーザーが例のJupyter Notebookバージョンをダウンロードできるようにします。
.py - ユーザーが例の.pyバージョンをダウンロードできるようにします。
.py.md5 - .pyファイルのMD5ハッシュ。ファイルに変更が加えられたかどうか、つまり新しい出力ファイルの生成が必要かどうかを判断するために使用されます。
.codeobj.json - 関数名とその関数が属するモジュールを特定するために使用されます（スクリプト内の関数名の特定の詳細）。

さらに、すべての.ipynbファイルと.pyファイルを含む2つの圧縮された.zipファイルが生成され、ルートレベルのsg_execution_times.rstファイルにはすべての実行時間が含まれます。

詳細な設定については、設定ページを参照してください。

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

ギャラリーのために生成されたindex.rstファイルは、メインのSphinxdoc/index.rstファイルの目次ツリーに追加するか、.. include::ステートメントを使用してSphinxソース.rstファイルに埋め込むことができます。

ドキュメントのビルド#

Sphinxのソースディレクトリ（例：myproject/doc）で、次を実行します。

$ make html

この操作で、ドキュメント全体のビルドが開始されます。上記で説明したSphinx-Galleryの出力ファイルと、SphinxでビルドされたHTMLドキュメントの両方が生成されます。ビルドが完了すると、サンプルからのすべての出力はキャッシュされます。次回以降は、変更されたサンプルのみが再ビルドされます。

これで、サンプルスクリプトからギャラリーが作成されました！より高度な使用方法と設定については、高度な使用方法ページまたは設定リファレンスをご覧ください。

注記

Sphinx-Galleryは、HTML以外のSphinx ビルダーでも動作する可能性がありますが、このサポートはほとんどテストされておらず、結果は異なる場合があります。