入門例 - sin のプロット#

これは、Matplotlib プロット出力、埋め込み reST、数式表記の使用、および他の例へのクロスリンクを示す一般的な例です。下記の出力を ソース Python ファイル と比較すると役立ちます。

ギャラリーの例のソースファイルは、三重引用符付きのヘッダードキュメント文字列で始める必要があります。ドキュメント文字列より前のものはすべて Sphinx-Gallery によって無視され、レンダリングされた出力には表示されず、実行もされません。このドキュメント文字列には、例のタイトルとして使用され、クロスリファレンスリンクを正しく構築するために使用される reST ヘッダーが必要です。

コードと埋め込み reST テキストブロックは、ドキュメント文字列の後に続きます。ドキュメント文字列直後の最初のブロックは、デフォルトではコードブロックとみなされます。ただし、# の行または #%% を使用してテキストブロックとして指定することもできます (下記参照)。すべてのコードブロックは Sphinx-Gallery によって実行され、プロットを含むすべての出力がキャプチャされます。通常、コードブロックとテキストブロックは、コードが行っていることの説明や、コード出力の解釈を提供するために、交互に配置されます。

数式は LaTeX として含めることができ、MathJax でレンダリングされます。表示される数式表記を含めるには、ディレクティブ .. math:: を使用します。インライン数式表記を含めるには、:math: ロールを使用します。たとえば、これから次の関数をプロットします。

\[x \rightarrow \sin(x)\]

ここで、関数 \(\sin\) は、変数 \(x\) が定義されている各点で評価されます。Python 文字列に LaTeX を含める場合は、バックスラッシュをエスケープするか、raw ドキュメント文字列を使用してください。テキストブロックではこれを行う必要はありません (下記参照)。

# Code source: Óscar Nájera
# License: BSD 3 clause

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 2 * np.pi, 100)
y = np.sin(x)

plt.plot(x, y)
plt.xlabel(r"$x$")
plt.ylabel(r"$\sin(x)$")
# To avoid matplotlib text output
plt.show()

埋め込み reST を含めるには、reST とコードの間に 20 個以上の # または #%% の行を使用します(例のPythonファイルにreSTを埋め込むを参照)。これにより、例が別々のテキストブロックとコードブロックに分割されます。埋め込み reST テキストブロックの下にコードを書き続けることができます。

print("This example shows a sin plot!")

This example shows a sin plot!

テキストブロック内の LaTeX 構文では、バックスラッシュをエスケープする必要はありません。

\[\sin\]

相互参照#

ドキュメントの任意の部分から、他の例を含め、例を参照することができます。Sphinx-Gallery は、各例に対して参照ラベルを自動的に作成します。ラベルは、.py ファイル名に、sphx_glr_ と、例が含まれるフォルダー名がプレフィックスとして付いたものです。以下では、クロスリファレンスしたい例は、auto_examples ( gallery_dirs を参照;Sphinx-Gallery の構成と使用) にあり、次にサブディレクトリ no_output にあります (例がサブギャラリー内にあるため)。例のファイル名は plot_syntaxerror.py です。したがって、例「SyntaxError」へのクロスリンクは、:ref:`sphx_glr_auto_examples_no_output_plot_syntaxerror.py` を使用して行うことができます。