Sphinx-Gallery用Pythonスクリプトの構造#
このページでは、レンダリングされたHTMLギャラリーページを生成するためにPythonスクリプトで使用できる構造と構文について説明します。
簡単な例#
Sphinx-Galleryは、各Pythonファイルに次の2つの要素を期待します。
docstring: reSTで記述された、例のヘッダーを定義します。reSTのタイトルを定義することから始める必要があります。タイトルには任意の句読点を含めることができますが、同じ句読点を3回以上繰り返して始めることはできません。例えば
""" "This" is my example-script =========================== This example doesn't do much, it just makes a simple plot """
Pythonコード: これは、任意の有効なPythonコードです。生成されたMatplotlib画像はディスクに保存され、生成されたreSTはこれらの画像を組み込みの例と共に表示します。デフォルトでは、MatplotlibまたはMatplotlibベースのパッケージ（例：SeabornやYellowbrick）によって生成された画像のみが保存および表示されます。ただし、他のパッケージを含めるように変更できます。画像スクレイパーを参照してください。
クイックリファレンスとして、例導入例 - sinのプロットを参照してください。
例となるPythonファイルへのreSTの埋め込み#
さらに、Pythonスクリプト内にreST構文を埋め込むことができます。reSTを使用すると、フォーマットされたテキスト、数式、参照リンク（他の例のクロスリファレンスを含む）を簡単に追加できます。これは、Jupyter Notebookの構造と同様に、Pythonコードとその出力と共にインラインでレンダリングされます（実際、Sphinx-Galleryは構築される各例に対してJupyter Notebookも作成します）。
20個以上の#記号、#%%、または# %%を含む行を挿入することで、Python例にreSTを埋め込むことができます。一貫性のため、プロジェクトでは上記の3つの「ブロック区切り」オプションのいずれか1つのみを使用することをお勧めします。#の行を使用する場合は、79個の#を使用することをお勧めします。
###############################################################################
ブロック区切りに続くコメント行（#で始まり、PEP8準拠のためにスペースが続く行）は、構築されたギャラリー例でreSTとしてレンダリングされます。コードの記述に戻すには、#とスペースで始まる行を停止するか、コードコメントの前に空行を残します。このようにして、テキストとコードの「ブロック」を簡単に切り替えることができます。例えば
# This is commented python
myvariable = 2
print("my variable is {}".format(myvariable))
# %%
# This is a section header
# ------------------------
#
# In the built documentation, it will be rendered as reST. All reST lines
# must begin with '# ' (note the space) including underlines below section
# headers.
# These lines won't be rendered as reST because there is a gap after the last
# commented reST block. Instead, they'll resolve as regular Python comments.
# Normal Python code can follow these comments.
print('my variable plus 2 is {}'.format(myvariable + 2))
#%%と# %%構文は、Visual Studio Code Python拡張機能、Visual Studio Pythonツール、Jupytext、Pycharm Professional、Hydrogenプラグイン（Atom用）、およびSpyderの「コードブロック」（または「コードセル」）区切り構文と一貫しています。これらのエディター/IDEのドキュメントでは#%%または# %%のいずれか1つしか言及されていない場合がありますが、実際にはどちらも機能します。これらのエディター/IDEでは、行の先頭にある#%%または# %%は新しいコードブロックの開始を示します。コードブロックを使用すると、Jupyter Notebookのようにコードをチャンクに分割できます。コードブロック内のすべてのコードをまとめて簡単に実行できます。この機能は、ブロックを使用してSphinx-Galleryのテキストとコードのブロックのペアを簡単に作成できるため、Sphinx-Galleryの.py例を作成する際に役立ちます。
ここに、「コードブロック」機能を使用した例となるPythonファイルの内容を示します。
"""
This is my example script
=========================
This example doesn't do much, it just makes a simple plot
"""
# %%
# This is a section header
# ------------------------
# This is the first section!
# The `#%%` signifies to Sphinx-Gallery that this text should be rendered as
# reST and if using one of the above IDE/plugin's, also signifies the start of a
# 'code block'.
# This line won't be rendered as reST because there's a space after the last block.
myvariable = 2
print("my variable is {}".format(myvariable))
# This is the end of the 'code block' (if using an above IDE). All code within
# this block can be easily executed all at once.
# %%
# This is another section header
# ------------------------------
#
# In the built documentation, it will be rendered as reST after the code above!
# This is also another code block.
print('my variable plus 2 is {}'.format(myvariable + 2))
明確な例については、レンダリングされた例テキストとコードの交互表示を参照し、生成された元のPythonスクリプトと比較してください。
他のプログラミング言語の例#
Sphinx-Galleryは、Python以外のプログラミング言語で記述された例についてもHTMLページのレンダリングをサポートしていますが、これらの例は現在実行または出力のスキャンが行われていません。ファイル名/無視パターンで設定を参照してください。
このような例では、例のヘッダーはファイルの最初のコメントブロックによって定義され、reSTタイトルを含み、最初のコードブロックの上に表示される追加のreSTコンテンツを含めることができます。例えば、C++の例は次のように開始できます。
// My Awesome Example
// ==================
//
// The description continues as long as there are lines
// that start with a comment character.
reSTコンテンツは、特別な区切り文字でマークされたコメントにも同様に埋め込むことができます。その区切り文字は、例の言語で使用されるコメント文字によって異なります。有効な特別な区切り文字は次のとおりです。
コメント文字の後に
%%が続く。例：C++の場合は//%%。コメント文字の後にスペース、さらに
%%が続く。例：C++の場合は// %%。20個以上のコメント文字の行。例：C++の場合は
////////////////////。
同じ行で特別な区切り文字の後に続くテキストは、reST見出し（-で下線が引かれている）に変換されます。reSTブロックは、コメント文字で始まらない行が検出されるまで続きます。いくつかの例
// %% Important Heading
// This is some text in a reST block in C++, appearing underneath a heading.
//
// * Start a list
// * Check it twice
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! This is the start of a reST block in Fortran 90.
!
! It can contain multiple paragraphs.
Cスタイルの複数行コメントを使用する言語では、次のスタイルがサポートされています。
/* %%
* Subheading
* ----------
*
* Description
*/
int y = 3;
/**************************/
/* Another subheading */
/* ------------------ */
/* */
/* Description */
/**************************/
double z = 1.5;
最後に、Matlabがコードセクションをマークするために単純な%%区切り文字を使用することとの互換性のために、これは上記の複数言語構文に加えて、Matlabソースファイルで特別な区切り文字として許可されています。
%% Heading
% some text below the heading
プレーンreSTの例#
Sphinx-GalleryはPythonスクリプトから例を生成するため、プレーンreSTファイルで記述された例はサポートされていません。通常のreSTドキュメントのコードブロックで関数へのハイパーリンク（対応するオンラインドキュメントへのリンク）を生成したい場合は、sphinx-codeautolinkが役立つ場合があります。