為 Sphinx-Gallery 建構 Python 腳本#

本頁描述可在 Python 腳本中使用的結構和語法，以產生渲染的 HTML 範例頁面。

一個簡單的範例#

Sphinx-Gallery 期望每個 Python 檔案都有兩件事：

一個 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）產生的圖片。但是，您可以更改此設定以包含其他套件，請參閱圖片抓取器。

在您的範例 Python 檔案中嵌入 reST#

此外，您可以在 Python 腳本中嵌入 reST 語法。reST 讓您可以輕鬆新增格式化文字、數學方程式和參考連結，包括交叉引用其他範例。這將與 Python 程式碼及其輸出內嵌呈現，類似於 Jupyter Notebooks 的結構（事實上，Sphinx-Gallery 也會為每個建立的範例建立一個 Jupyter Notebook）。

您可以在 Python 範例中嵌入 reST，方法是加入一行 >= 20 個 # 符號、#%% 或 # %%。為了保持一致性，建議您在專案中僅使用以上三個「區塊分隔符」選項之一。如果使用一行 # 符號，我們建議使用 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 的文件可能僅提及 #%% 或 # %% 其中之一，但實際上兩者都可以運作。使用這些編輯器/IDE，行開頭的 #%% 或 # %% 表示新程式碼區塊的開始。程式碼區塊可讓您將程式碼分成多個區塊，就像 Jupyter Notebooks 中一樣。程式碼區塊中的所有程式碼都可以輕鬆地一起執行。當您編寫 Sphinx-Gallery .py 範例時，此功能會很有幫助，因為這些區塊可讓您輕鬆建立成對的後續 Sphinx-Gallery 文字和程式碼區塊。

以下是使用「程式碼區塊」功能的範例 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 很有幫助。