入門範例 - 繪製 sin 函數#

這是一個通用範例，示範 Matplotlib 繪圖輸出、嵌入的 reST、數學符號的使用以及連結到其他範例。比較原始 Python 檔案與下方輸出會很有幫助。

範例展示的原始檔案應以三引號標頭的 docstring 開始。 docstring 之前的任何內容都會被 Sphinx-Gallery 忽略，並且不會出現在呈現的輸出中，也不會被執行。此 docstring 需要 reST 標頭，用作範例的標題，並正確建立交叉參照連結。

程式碼和嵌入的 reST 文字區塊位於 docstring 之後。預設情況下，docstring 之後的第一個區塊會被視為程式碼區塊，除非您使用一行 # 或 #%% 將其指定為文字區塊 (請參閱下方)。所有程式碼區塊都會由 Sphinx-Gallery 執行，並擷取任何輸出，包括繪圖。通常，程式碼和文字區塊會穿插使用，以提供程式碼正在執行的內容或程式碼輸出的解釋。

數學表達式可以包含為 LaTeX，並將使用 MathJax 呈現。若要包含顯示的數學符號，請使用指令 .. math::。若要包含內嵌數學符號，請使用 :math: 角色。例如，我們即將繪製以下函數

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

這裡函數 \(\sin\) 在定義變數 \(x\) 的每個點進行評估。在 Python 字串中包含 LaTeX 時，請確保您逸出反斜線或使用原始 docstring。您不需要在文字區塊中執行此操作 (請參閱下方)。

# 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`。