Sphinx-Gallery 入門

建立基本範例集

本節說明如何使用 Sphinx 擴展 Sphinx-Gallery 為您的範例設定基本範例集，它將執行以下操作：

• 自動從您的 .py 範例檔案產生 Sphinx reST。產生的 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 教學建立網站。

• 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 腳本：一組 Python 腳本，將在您建置 HTML 文件時進行處理。有關如何使用嵌入式 reST 建構這些 Python 腳本的資訊，請參閱為 Sphinx-Gallery 組織 Python 腳本。

  • 預設情況下，只有以 plot_ 為前綴的檔案才會被執行，並且其輸出會被擷取，以將其合併到腳本的 HTML 輸出中。沒有該前綴的檔案只會被解析並以豐富的程式設計方式呈現，而不會有任何輸出。若要變更執行和擷取的預設檔案模式，請參閱透過比對模式解析和執行範例。

  • 可以精細調整在執行 .py 檔案時擷取並隨後合併到建置的文件中的輸出。請參閱控制擷取的輸出。

  • 您可以在 examples 目錄中建立子目錄。這些子目錄將被包含為範例集的子章節。它們必須也包含自己的 GALLERY_HEADER.[ext] 檔案。請注意，[ext] 可以是 'txt' 或 sphinx_gallery_conf["source_suffix"] 中的項目。我們也為了向後相容性而支援 README.[ext]。

警告

變數名稱 ___（3 個底線）絕不應在您的範例 Python 腳本中使用，因為它被用作 Sphinx-Gallery 的內部變數。

設定和使用 Sphinx-Gallery

安裝 Sphinx-Gallery 後，我們必須啟用並設定它以使用 Sphinx 建置。

首先，在 Sphinx doc/conf.py 檔案中使用以下程式碼啟用 Sphinx-Gallery：

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

這會將 Sphinx-Gallery 作為您的其中一個擴充功能載入，省略符號 ... 代表您其他載入的擴充功能。

接下來，為 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 - 用於識別函數名稱以及它們所屬的模組（更多詳細資訊請參閱識別腳本中的函數名稱）

此外，還會產生兩個壓縮的 .zip 檔案，其中包含所有 .ipynb 和 .py 檔案，以及一個根層級的 sg_execution_times.rst 檔案，其中包含所有執行時間。

如需更進階的設定，請參閱設定頁面。

將您的範例集新增至文件

為您的範例集產生的 index.rst 檔案可以新增至主 Sphinx doc/index.rst 檔案中的目錄樹，或使用 .. include:: 陳述式嵌入到 Sphinx 來源 .rst 檔案中。

建置文件

在您的 Sphinx 原始碼目錄中 (例如，myproject/doc)，執行

$ make html

這將開始建置您的完整文件。上述的 Sphinx-Gallery 輸出檔案和 Sphinx 建置的 HTML 文件都會被產生。一旦建置完成，您所有範例的輸出將會被快取。未來，只有變更過的範例才會被重新建置。

您現在應該有一個由您的範例腳本建置的展示廊！如需更多進階用法和設定，請查看進階用法頁面或設定參考。

注意

Sphinx-Gallery 可能適用於非 HTML 的 Sphinx 建置器，但對此的支援大多未經測試，結果可能會有所不同。