設定#

Sphinx-Gallery 的設定與自訂主要透過在您的 conf.py 檔案中指定的字典完成。可能的鍵值列表列在下方，並在後續章節中詳細說明。

當使用這些標記時，良好的做法是確保原始 Python 檔案等同於產生的 HTML 和 iPython 筆記本 (例如，確保 .py == .html == .ipynb)。只有在必要時才應違反此原則，並且需逐個案例考慮。

設定選項#

全域 conf.py 設定#

可以在 Sphinx conf.py 檔案內的 sphinx_gallery_conf 字典中設定的 Sphinx-Gallery 設定選項。

展示檔案與排序

範例執行

交叉引用

圖片與縮圖

運算成本

Jupyter 筆記本與互動性

外觀

其他

範例內的設定#

某些選項也可以在每個檔案的基礎上設定或覆寫

某些選項可以在檔案中按程式碼區塊設定

某些選項可以在檔案中逐行設定：- # sphinx_gallery_start_ignore 和 # sphinx_gallery_end_ignore (參見隱藏程式碼行)

另請參閱移除設定註解，以隱藏檔案中呈現的範例中的設定註解。

建置選項#

某些選項可以在建置執行步驟中設定，例如使用 Makefile

CSS 變更#

某些項目可以直接在 CSS 中進行調整

移除警告#

為了避免警告被捕捉並包含在您建置的文件中，您可以在 conf.py 檔案中使用套件 warnings。例如，要移除特定的 Matplotlib agg 警告，您可以新增

import warnings

warnings.filterwarnings("ignore", category=UserWarning,
                        message='Matplotlib is currently using agg, which is a'
                                ' non-GUI backend, so cannot show the figure.'
                                '|(\n|.)*is non-interactive, and thus cannot be shown')

到您的 conf.py 檔案。

請注意，上述 Matplotlib 警告預設會被移除。

匯入可呼叫物件#

Sphinx-Gallery 設定值（已實例化的類別、類別或函式）應以完整限定名稱字串傳遞給物件。該物件必須可被 Sphinx-Gallery 匯入。

達成此目的的兩種常見方式是

  1. 使用您的套件定義您的物件。例如，您可以撰寫一個函式 def my_sorter 並將其放在 mymod/utils.py 中，然後使用

    sphinx_gallery_conf = {
#...,
"minigallery_sort_order": "mymod.utils.my_sorter",
#...
}

  2. 使用您的文件定義您的物件。例如，您可以在不同的路徑中新增文件特定的內容，並確保它可以在建置時被解析。例如，您可以建立一個檔案 doc/sphinxext.py 並定義您的函式

    def plotted_sorter(fname):
    return not fname.startswith("plot_"), fname

    並在您的設定中設定

    sys.path.insert(0, os.path.dirname(__file__))

sphinx_gallery_conf = {
#...,
"minigallery_sort_order": "sphinxext.plotted_sorter",
#...
}

    然後 Sphinx-Gallery 會將 "sphinxext.plotted_sorter" 解析為 plotted_sorter 物件，因為 doc/ 目錄位於路徑的最前面。

像 sphinx_gallery.sorting.FileNameSortKey 之類的內建類別可以使用較短的直接別名字串，例如 "FileNameSortKey"（詳細資訊請參閱排序圖庫範例）。

注意

Sphinx-Gallery > 0.16.0 支援使用完整限定名稱字串，以回應 Sphinx > 7.3.0 對 conf.py 檔案的快取和序列化檢查所做的變更。

這表示先前使用類別實例作為設定值以確保 __repr__ 在建置過程中保持穩定的做法是多餘的，如果您是透過名稱字串傳遞設定值。當使用名稱字串時，設定物件可以只是一個函式。

確保穩定的 __repr__#

為了向後相容性，Sphinx-Gallery 允許某些設定值是可呼叫物件而不是可匯入的名稱字串。

如果您希望使用可呼叫物件，您必須確保 __repr__ 在執行過程中保持穩定。Sphinx 會透過在 sphinx/builders/html.py 中使用 md5(str(obj).encode()).hexdigest() 來檢查設定值，以判斷建置環境是否已變更，進而判斷是否應重寫 *所有* 文件。Python 中的預設類別實例的 __repr__ 中有其記憶體位址，這就是為什麼 __repr__ 通常在每次建置中都會變更的原因。

您的可呼叫物件應該是一個定義穩定 __repr__ 方法的類別。例如，sphinx_gallery.sorting.ExplicitOrder 的穩定性是透過自訂的 __repr__ 來確保的

def __repr__(self):
    return '<%s: %s>' % (self.__class__.__name__, self.ordered_list)

因此，只有在指定的排序清單變更時，才會全部重建檔案。

管理多個圖庫#

Sphinx-Gallery 僅支援其圖庫目錄中一個層級的子資料夾巢狀結構。例如，我們的使用 Matplotlib 的基礎圖庫，其父圖庫位於 examples/ 中，而子區段（又稱子圖庫）位於 examples/no_output/ 中。不支援更深層的子資料夾。這對您來說可能是一個限制。或者，您可能希望針對不同的目的設定不同的圖庫；一個範例圖庫和一個教學圖庫。若要執行此操作，請在您的 Sphinx conf.py 檔案中將 Sphinx-Gallery 設定字典鍵 examples_dirs 和 gallery_dirs 設定為目錄清單

sphinx_gallery_conf = {
    ...
    'examples_dirs': ['../examples', '../tutorials'],
    'gallery_dirs': ['auto_examples', 'tutorials'],
}

請記住，這兩個清單的長度必須相同。

注意

如果您的範例執行時間很長，請考慮查看為每個圖庫目錄產生的執行時間檔案（只要在建置期間該目錄中實際執行了任何範例），以及所有圖庫的整體執行時間。

透過比對模式剖析和執行範例#

預設情況下，Sphinx-Gallery 會剖析並新增所有副檔名為 .py 的檔案到圖庫中，但只會執行以 plot_ 開頭的檔案。這些行為由 ignore_pattern、filename_pattern 和 example_extensions 條目控制，這些條目的預設值為

sphinx_gallery_conf = {
    ...
    'filename_pattern': '/plot_',
    'ignore_pattern': r'__init__\.py',
    'example_extensions': {'.py'}
}

若要完全從圖庫中省略某些檔案（也就是說，不執行、剖析或新增它們），您可以變更 ignore_pattern 選項。若要選擇實際執行哪些已剖析和新增的 Python 指令碼，您可以修改 filename_pattern。例如

sphinx_gallery_conf = {
    ...
    'filename_pattern': '/plot_compute_',
}

將會建置所有以 plot_compute_ 開頭的範例。鍵 filename_pattern (和 ignore_pattern) 接受將與範例完整路徑比對的正規表示式。這就是為什麼需要前導的 '/' 的原因。建議使用者使用 re.escape(os.sep) 而不是 '/'，如果他們想要不依賴作業系統。

如果您只想建置範例的子集，filename_pattern 選項也很有用。例如，您可能只想建置一個範例，以便您可以在文件中連結它。在這種情況下，您應該執行

sphinx_gallery_conf = {
    ...
    'filename_pattern': r'plot_awesome_example\.py',
}

在這裡，您應該逸出點 r'\.'，否則 Python 正規表示式 會比對任何字元。儘管如此，由於目標是特定檔案，即使沒有這個逸出字元，它也會比對檔案名稱中的點。

注意

Sphinx-Gallery 只會重新執行已變更的範例（根據其 md5 雜湊）。有關資訊，請參閱下方的重新執行過時的範例。

同樣地，若要只建置特定目錄中的範例，您可以執行

sphinx_gallery_conf = {
    ...
    'filename_pattern': '/directory/plot_',
}

或者，您可以跳過執行某些範例。例如，若要跳過建置以 plot_long_examples_ 開頭的範例，您應該執行

sphinx_gallery_conf = {
    ...
    'filename_pattern': '/plot_(?!long_examples)',
}

由於模式是剖析為 正規表示式，因此建議使用者查閱 正規表示式 模組以取得更多詳細資料。

注意

請記住，Sphinx 允許從命令列覆寫 conf.py 值，因此例如，您可以透過類似的方式直接建置單一範例

$ sphinx-build -D sphinx_gallery_conf.filename_pattern=plot_specific_example\.py ...

您也可以透過將其他語言的副檔名新增到 example_extensions 來剖析和醒目顯示其他語言的語法範例，儘管它們不會被執行。例如，若要包含 Python、Julia 和 C++ 中的範例

sphinx_gallery_conf = {
    ...
    'example_extensions': {'.py', '.jl', '.cpp'}
}

Pygments 程式庫支援剖析和語法醒目顯示，語言由副檔名決定。若要覆寫 Pygments 的預設檔案關聯，可以使用 filetype_parsers 選項來指定 dict，將 example_extensions 中的任何副檔名對應到任何pygments 語言名稱。例如

sphinx_gallery_conf = {
    ...
    'filetype_parsers': {'.m': 'Matlab'}
}

重新執行過時的範例#

預設情況下，Sphinx-Gallery 只會重建已變更的範例。例如，當從一個乾淨的 doc/ 目錄開始時，執行一次 HTML 建置將會導致 Sphinx-Gallery 執行所有符合您指定的檔案名稱/忽略模式的範例。然後，第二次執行完全相同的命令不應該執行任何範例，因為每個範例的 MD5 雜湊值將會與第一次建置時範例檔案的 MD5 雜湊值（以 <filename>.md5 儲存在產生的目錄中）進行比對。這些雜湊值將會匹配，因此會判定範例為「過時」，並且 Sphinx-Gallery 將不會重建該範例。此設計特性允許僅在範例變更時才重建範例，從而加速文件迭代。

然而，這在某些除錯和迭代模式下會產生問題。假設您有一個特定的範例，您想在修改底層函式庫中的某些函式時重複重建，但不希望變更範例檔案本身的內容。要做到這一點，您需要對範例進行一些變更（例如，新增/刪除換行符號），或刪除 .md5 檔案，以強制 Sphinx-Gallery 重建範例。或者，您可以使用以下組態值：

sphinx_gallery_conf = = {
    ...
    'run_stale_examples': True,
}

透過此設定，即使 MD5 雜湊值顯示範例沒有變更，所有符合檔案名稱/忽略模式的範例都會被重建。您可以將此設定與檔案名稱/忽略模式結合使用，以重複重新執行單一範例。例如，這可以透過命令列完成：

$ make html SPHINXOPTS="-D sphinx_gallery_conf.run_stale_examples=True -D sphinx_gallery_conf.filename_pattern='my_example_name'"

此命令將導致任何符合檔案名稱模式 'my_example_name' 的範例被重建，無論其 MD5 雜湊值為何。

傳遞命令列引數至範例腳本#

預設情況下，Sphinx-Gallery 不會將任何命令列引數傳遞給範例腳本。透過設定 reset_argv 選項，可以變更此行為並將命令列引數傳遞給範例腳本。reset_argv 需要是一個 Callable，它接受 gallery_conf 和 script_vars 字典作為輸入，並傳回一個字串列表，這些字串會作為額外的命令列引數傳遞給直譯器。

reset_argv 的範例可能是：

from pathlib import Path

def reset_argv(sphinx_gallery_conf, script_vars):
    src_file = Path(script_vars['src_file']).name
    if src_file == 'example1.py':
        return ['-a', '1']
    elif src_file == 'example2.py':
        return ['-a', '2']
    else:
        return []

此函式定義在 doc/sphinxext.py 中，我們確保它是可匯入的（請參閱匯入可呼叫物件）。

這可以包含在組態字典中，如下所示：

sphinx_gallery_conf = {
    ...
    'reset_argv': "sphinxext.reset_argv",
}

然後 Sphinx-Gallery 會將其解析為可呼叫物件 reset_argv 並使用，如下所示：

import sys
sys.argv[0] = script_vars['src_file']
sys.argv[1:] = reset_argv(gallery_conf, script_vars)

注意

為了向後相容，您也可以將組態設定為可呼叫物件，但您必須確保 __repr__ 在多次執行中保持穩定。請參閱確保穩定的 __repr__。

自訂排序鍵#

您可以為以下組態建立自訂排序鍵可呼叫物件：

最好的方法是定義一個排序函式，該函式接受傳遞的路徑字串：

def plotted_sorter(fname):
    return not fname.startswith("plot_"), fname

確保它是可匯入的（請參閱匯入可呼叫物件），並設定您的組態：

sphinx_gallery_conf = {
#...,
"minigallery_sort_order": "sphinxext.plotted_sorter",
#...
}

為了向後相容，您也可以將組態設定為可呼叫物件，但您必須確保 __repr__ 在多次執行中保持穩定。請參閱確保穩定的 __repr__以取得詳細資訊。

我們建議您使用 sphinx_gallery.sorting.FunctionSortKey，因為它會確保 __repr__ 在多次執行中保持穩定。

sphinx_gallery.sorting.FunctionSortKey 在初始化時接受一個函式。您可以透過使用排序鍵函式實例化 FunctionSortKey 實例來建立您的排序鍵可呼叫物件。例如，以下 minigallery_sort_order 組態（它會依路徑排序）將會使用每個檔案名稱的前 10 個字母進行排序：

sphinx_gallery_conf = {
#...,
"minigallery_sort_order": FunctionSortKey(
    lambda filename: filename[:10]),
#...
}

新增迷你範例集#

Sphinx-Gallery 提供了 sphinx_gallery.directives.MiniGallery 指令，讓您可以輕鬆地將簡化版的範例集新增到您的 Sphinx 文件 .rst 檔案中。因此，迷你範例集指令支援傳遞任何以下項目的清單（以空格分隔）

要使用物件名稱，您必須啟用反向參照生成，請參閱新增 API 文件的迷你範例集以取得詳細資訊。如果未啟用反向參照生成，則 MiniGallery 指令的物件條目將被忽略，所有條目將被視為路徑字串或 glob 樣式的路徑字串。請參閱使用檔案路徑建立迷你範例集以取得詳細資訊。

新增 API 文件的迷你範例集#

Sphinx-Gallery 可以為指定模組中的物件生成迷你範例集，其中包含以下所有範例：

  1. 在程式碼中使用函式/方法/屬性/物件或實例化類別（稱為隱式反向參照），或

  2. 在文字區塊中使用 sphinx 標記 :func: / :meth: / :attr: / :obj: / :class: 參照該函式/方法/屬性/物件/類別。如果您已將 default_role 在您的 conf.py 中設定為任何這些角色，則可以省略此角色標記（稱為顯式反向參照）。

這允許您將物件的完整限定名稱（例如，函式、方法、屬性、類別）傳遞到迷你範例集指令，以新增所有與該物件相關的範例的迷你範例集。這在 API 文件中很有用。

隱式反向參照對於自動記錄程式碼中使用且明確實例化的物件和類別很有用。程式碼中使用物件的任何範例都會隱式新增為反向參照。顯式反向參照適用於在範例文字中顯式參照的物件。它們適用於通常在程式碼中隱式返回而不是明確實例化的類別（例如，matplotlib.axes.Axes，它通常僅在函式呼叫中以間接方式實例化）。

例如，我們可以嵌入一個小型範例集，其中包含使用或參照 numpy.exp 的所有範例，看起來像這樣

使用 numpy.exp 的範例#

繪製指數函數

繪製指數函數

選擇縮圖圖像

選擇縮圖圖像

識別腳本中的函式名稱

識別腳本中的函式名稱

要使此行為可用，您必須在您的 Sphinx-Gallery 組態 conf.py 檔案中使用以下內容啟用它

sphinx_gallery_conf = {
    ...
    # directory where function/class granular galleries are stored
    'backreferences_dir'  : 'gen_modules/backreferences',

    # Modules for which function/class level galleries are created. In
    # this case sphinx_gallery and numpy in a tuple of strings.
    'doc_module'          : ('sphinx_gallery', 'numpy'),

    # Regexes to match objects to exclude from implicit backreferences.
    # The default option is an empty set, i.e. exclude nothing.
    # To exclude everything, use: '.*'
    'exclude_implicit_doc': {r'pyplot\.show'},
}

您在 backreferences_dir 中指定的路徑（這裡我們選擇 gen_modules/backreferences）將會填入 ReStructuredText 檔案，其名稱以「.examples」結尾。每個 .rst 檔案都將包含一個簡化版的範例集，該範例集專屬於所有範例中使用且屬於 doc_module 中列出的模組的每個函式/類別。請注意，將為所有物件生成反向參照檔案。任何範例中未使用的物件將具有空檔案，以防止自動文件解析期間的包含錯誤。

backreferences_dir 應該是相對於 conf.py 檔案的相對字串或 pathlib.Path 物件，或者 None。預設情況下它是 None。

有時，某些函式幾乎在給定模組的每個範例中都被使用，例如 Matplotlib 中的 pyplot.show 或 pyplot.subplots 函式，因此大量且通常不相關的範例將連結到這些函式。為了防止這種情況，您可以透過將它們作為正規表示式包含在 exclude_implicit_doc 中，來排除某些物件的隱式反向參照。以下設定將排除任何隱式反向參照，以便僅針對文件中使用 Sphinx 標記明確提及的物件建立範例集： {'.*'}。要排除上面提到的函式，您可以使用 {r'pyplot\.show', r'pyplot\.subplots'}（請注意，如果名稱沒有歧義，您也可以寫成 pyplot.show 或僅寫成 show，則需跳脫符號以比對點而不是任何字元）。

使用檔案路徑建立迷你範例集#

有時，您可能想要明確地使用沒有共同函式的檔案來建立 mini-gallery，例如一組教學課程。因此，迷你範例集指令也支援傳遞

  • 指向 sphinx 範例檔案的路徑字串（相對於 conf.py）

  • 指向 Sphinx-Gallery 範例檔案的 glob 樣式路徑字串（相對於 conf.py）

例如，下面的 rst 會為所有使用特定函式 numpy.exp 的範例、examples/plot_sin_.py 範例以及所有符合字串 /examples/plot_4* 的檔案，新增簡化版的範例集。

.. minigallery::
    :add-heading:

    numpy.exp
    ../examples/plot_0_sin.py
    ../examples/plot_4*

列出多個項目會將所有範例合併到單個迷你範例集中。僅當檔案存在或項目實際在範例中使用或參照時，才會顯示迷你範例集。如果縮圖對應於多個物件名稱或物件名稱和檔案/glob 輸入，則縮圖也可能會重複。

使用多個物件之一的範例#

入門範例 - 繪製 sin

入門範例 - 繪製 sin

選擇縮圖圖像

選擇縮圖圖像

為縮圖影像提供圖形

為縮圖影像提供圖形

繪製指數函數

繪製指數函數

選擇縮圖圖像

選擇縮圖圖像

識別腳本中的函式名稱

識別腳本中的函式名稱

您也可以在指令的主體中提供項目清單

.. minigallery::
    :add-heading:

    numpy.exp
    ../examples/plot_0_sin.py
    ../examples/plot_4*

add-heading 選項會為迷你範例集新增標題。如果沒有提供字串參數，則僅列出單個項目時，預設標題為

「使用{完整限定物件名稱}的範例」

建議為包含多個項目的範例集指定自訂標題訊息，否則預設訊息為

「多個物件之一的範例」。

上面顯示的範例迷你範例集使用預設標題層級 ^。可以使用 heading-level 選項來變更此設定，該選項接受單個字元（例如，-）。

您也可以將輸入作為以空格分隔的參數清單傳遞給迷你範例集指令

.. minigallery:: numpy.exp ../examples/plot_0_sin.py ../examples/plot_4*

切換全域變數檢查#

預設情況下，Sphinx-Gallery 將在每個程式碼區塊的末尾檢查全域變數（和程式碼物件），以嘗試尋找變數和方法呼叫的類別。它也會嘗試尋找在類別上呼叫的方法。例如，此程式碼

lst = [1, 2]
fig, ax = plt.subplots()
ax.plot(lst)

應該以以下連結結束（假設已正確設定 intersphinx）：

但是，此功能可能並非在所有情況下都能正常運作。此外，如果變數名稱在同一個腳本中被重複使用來參照不同的類別，則會失效。

若要停用此全域變數內省功能，您可以使用組態鍵：

sphinx_gallery_conf = {
    ...
    'inspect_global_variables'  : False,
}

使用自訂預設縮圖#

如果您想對沒有產生任何繪圖的範例縮圖使用自己的影像，您可以透過編輯您的 Sphinx conf.py 檔案來指定它。您需要在組態字典中新增一個名為 default_thumb_file 的鍵。例如：

sphinx_gallery_conf = {
    ...
    'default_thumb_file': 'path/to/thumb/file.png',
}

在範例中新增行號#

可以透過新增全域 line_numbers 設定，在清單中顯示行號：

sphinx_gallery_conf = {
    ...
    'line_numbers': True,
}

或透過在範例腳本中新增註解，這會覆寫任何全域設定：

# sphinx_gallery_line_numbers = True

移除組態註解#

某些組態可以在檔案中透過新增具有模式 # sphinx_gallery_config [= value] 的特殊註解來指定到範例原始檔。預設情況下，原始檔會按原樣解析，因此註解會出現在範例中。

若要從已呈現的範例中移除註解，請設定選項：

sphinx_gallery_conf = {
    ...
    'remove_config_comments': True,
}

這只會從程式碼區塊中移除組態註解，而不會從文字區塊中移除。但是請注意，從技術上講，檔案級別的組態註解在放置於程式碼區塊或文字區塊中時都有效。

新增您自己的第一個和最後一個筆記本儲存格#

Sphinx-Gallery 允許您將自己的第一個和/或最後一個儲存格新增到每個產生的筆記本。新增第一個儲存格對於包含需要在筆記本中正確執行，但不需要在 .py 檔案中執行的程式碼可能很有用。預設情況下，不會新增第一個儲存格。

新增最後一個儲存格對於執行所需動作（例如報告使用者的環境）可能很有用。預設情況下，不會新增最後一個儲存格。

您可以透過修改 first_notebook_cell 和 last_notebook_cell 組態參數來選擇您喜歡的任何文字。例如，您可以新增以下第一個儲存格：

# This cell is added by Sphinx-Gallery
# It can be customized to whatever you like

這可以透過以下組態實現：

sphinx_gallery_conf = {
    ...
    'first_notebook_cell': ("# This cell is added by Sphinx-Gallery\n"
                            "# It can be customized to whatever you like\n"
                            )
}

可以透過類似的方式設定 last_notebook_cell 參數來新增最後一個儲存格：

sphinx_gallery_conf = {
    ...
    'first_notebook_cell': ("# This cell is added by Sphinx-Gallery\n"
                            "# It can be customized to whatever you like\n"
                            ),
    'last_notebook_cell': "# This is the last cell",
}

如果將 first_notebook_cell 或 last_notebook_cell 的值設定為 None，則不會將額外的第一個或最後一個儲存格新增到筆記本。

將影像新增至筆記本#

在產生筆記本時，預設情況下 (notebook_images = False)，來自 reST 文件區塊中 image 指令的影像路徑（而非從程式碼產生的影像）會使用其原始路徑包含在 markdown 中。這包含預期存在於本機檔案系統上的影像路徑，對於下載筆記本的使用者來說，這種情況不太可能發生。

透過設定 notebook_images = True，影像將透過 Base64 編碼的 資料 URI 內嵌到產生的筆記本中。由於透過資料 URI 包含影像可能會大幅增加筆記本的大小，因此建議僅在整個圖庫中使用小型影像時才使用此方法。

另一種替代方法是提供一個前置字串，該字串將用於影像，例如您的文件託管所在位置的根 URL。例如，以下組態：

sphinx_gallery_conf = {
    ...
    'examples_dirs': ['../examples'],
    'gallery_dirs': ['auto_examples'],
    ...
    'notebook_images': 'https://project.example.com/en/latest/',
    ...
}

以及 reST 文件區塊中範例 image 指令：

.. image:: ../_static/example.jpg
    :alt: An example image

圖片將會被加入到產生的筆記本中，並指向來源 URL https://project.example.com/en/latest/_static/example.jpg。請注意，上述 reST 範例中的圖片路徑是相對路徑，因此 URL 不包含 auto_examples，因為 ../ 向上移動了一個目錄，到達文件來源目錄。相對和絕對（從來源目錄起算）路徑都支援；所以在上面的範例中，/_static/example.jpg 也會產生相同的 URL。

請注意，前綴會直接套用，因此如果需要，前綴應該包含尾部的 /。

提示

如果在託管服務上建置多個版本的文件並使用前綴，請考慮使用 sphinx build -D 命令列選項，以確保連結指向正確的版本。例如

sphinx-build \
    -b html \
    -D sphinx_gallery_conf.notebook_images="https://project.example.com/docs/${VERSION}/" \
    source_dir build_dir

使用 pypandoc 將 reST 轉換為 markdown#

Sphinx-Gallery 可以使用 pypandoc (如果已安裝) 將 reST 文字區塊轉換為 markdown，用於每個範例產生的 iPython 筆記本 (.ipynb 檔案)。這些檔案與原始的 .py 版本一起在每個範例的底部提供下載。

Sphinx-Gallery 的 reST 到 markdown 轉換器對於較複雜的 reST 語法支援有限。如果您的範例具有更複雜的 reST，pypandoc 可能會產生更好的結果。預設情況下，'pypandoc' 配置設為 False，並且不會使用 pypandoc。

要使用 pypandoc，您可以設定

sphinx_gallery_conf = {
    ...
    'pypandoc': True,
}

您也可以透過設定 pypandoc.convert_text() 參數 extra_args 和 filters 來使用 pandoc 選項。要使用這些參數，請將 'pypandoc' 配置設定為關鍵字引數的字典

sphinx_gallery_conf = {
    ...
    'pypandoc': {'extra_args': ['--mathjax',],
                 'filters': ['pandoc-citeproc',],
}

警告

某些 pandoc 選項可能會導致不良影響。請謹慎使用。

使用 JUnit XML 檔案#

Sphinx-Gallery 可以建立一個包含您的範例執行時間、成功和失敗的 JUnit XML 檔案。若要在 /build 輸出目錄中建立名為（例如）junit-result.xml 的檔案，請設定配置鍵（路徑相對於 HTML 輸出目錄）

sphinx_gallery_conf = {
    ...
    'junit': '../test-results/sphinx-gallery/junit.xml',
}

預設情況下，JUnit XML 檔案產生功能已停用（透過設定 'junit': ''）。JUnit XML 檔案對於 CircleCI 建置很有用，您可以在其中加入如下一行，以在 CircleCI GUI 中取得您的範例執行時間摘要（這會解析檔案路徑 doc/_build/test-results/sphinx-gallery/junit.xml，並根據巢狀子目錄名稱推斷測試來自 sphinx-gallery）

- store_test_results:
    path: doc/_build/test-results
- store_artifacts:
    path: doc/_build/test-results

有關 CircleCI 整合的更多資訊，請詳閱相關的 CircleCI 文件 和 部落格文章。

設定日誌層級#

Sphinx-Gallery 會在幾個階段記錄輸出。當在不支援區分大小寫命名 (例如 Windows) 的檔案系統上建置文件時，可能會為需要區分大小寫的程式碼 (例如 plt.subplot 和 plt.Subplot) 產生警告。在這種情況下，預設會發出 logger.warning，這將導致使用 -W 建置時建置失敗。可以使用以下設定日誌層級

sphinx_gallery_conf = {
    ...
    'log_level': {'backreference_missing': 'warning'},
}

目前唯一有效的鍵是 backreference_missing。有效值為 'debug'、'info'、'warning' 和 'error'。

停用所有腳本的下載按鈕#

預設情況下，Sphinx-Gallery 會將每個圖庫的所有 Python 腳本和所有 Jupyter 筆記本收集到 zip 檔案中，這些檔案可在每個圖庫的底部下載。要停用此行為，請在您的 conf.py 檔案中將其添加到配置字典中

sphinx_gallery_conf = {
    ...
    'download_all_examples': False,
}

選擇縮圖影像#

對於產生多個圖形的範例，預設行為會使用每個範例中建立的第一個圖形作為圖庫中顯示的縮圖影像。若要將縮圖影像變更為範例腳本中稍後產生的圖形，請在範例腳本中加入註解，以指定您要用作縮圖的圖形編號。例如，要使用建立的第二個圖形作為縮圖

# sphinx_gallery_thumbnail_number = 2

您也可以使用負數，從最後一個圖形開始計數。例如，-1 表示使用範例中建立的最後一個圖形作為縮圖

# sphinx_gallery_thumbnail_number = -1

預設行為是 sphinx_gallery_thumbnail_number = 1。請參閱 選擇縮圖圖形 以取得此功能的範例。

提供縮圖影像的影像#

可以使用任意影像作為範例的縮圖影像。若要指定用作縮圖的影像，請在範例腳本中加入註解，指定所需影像的路徑。影像的路徑應該相對於 conf.py 檔案，且註解應位於 docstring 下方的某個位置 (理想情況下是在程式碼區塊中，請參閱 移除配置註解)。

例如，以下定義應該使用 _static/ 資料夾中的 demo.png 影像來建立縮圖

# sphinx_gallery_thumbnail_path = '_static/demo.png'

請注意，sphinx_gallery_thumbnail_number 會覆蓋 sphinx_gallery_thumbnail_path。請參閱 為縮圖影像提供圖形 以取得此功能的範例。

控制失敗範例中的縮圖行為#

預設情況下，預期會失敗的範例的縮圖影像會是一個帶有「BROKEN」文字的印章。此行為由 sphinx_gallery_failing_thumbnail 控制，預設為 True。在需要控制縮圖影像的情況下，應該將其設定為 False。這會將縮圖行為還原為「正常」，縮圖將會是建立的第一個圖形（或者如果未建立任何圖形，則為預設縮圖）或提供的縮圖

# sphinx_gallery_failing_thumbnail = False

比較 無法執行的範例（具有正常縮圖行為）（其中選項為 False）和 無法執行的範例（其中選項為預設的 True）的縮圖，以取得此功能的範例。

使 Notebook 中的儲存格魔術可執行#

通常，教學課程會包含使用者可以複製/貼上到其終端機的 bash 程式碼。在有人建置文件時，不應執行此程式碼，因為他們的環境中已經有這些相依性。因此，它們通常以文字內的程式碼區塊形式撰寫。

#%%
# Installing dependencies
#
#     .. code-block:: bash
#
#       pip install -q tensorflow
#       apt-get -qq install curl

這對於 .py 和 .html 檔案來說效果很好，但是在呈現為 Jupyter Notebook 時會產生問題。下載的 .ipynb 檔案將不會安裝這些相依性，並且在沒有執行 bash 程式碼的情況下將無法運作。

為了修正此問題，我們可以在 conf.py 中設定 promote_jupyter_magic 旗標。

sphinx_gallery_conf = {
    ...
    'promote_jupyter_magic': True,
}

如果此旗標為 True，則當正在建置 Jupyter Notebook 時，任何以 Jupyter 儲存格魔術（例如 %%bash 或 %%writefile）開頭的程式碼區塊都將轉換為可執行的程式碼區塊。

對於我們之前的範例，我們可以將 Markdown 文字變更為

#%%
# Installing dependencies
#
#     .. code-block:: bash
#
#       %%bash
#       pip install -q tensorflow
#       apt-get -qq install curl

表示在執行 Jupyter Notebook 時會自動安裝 TensorFlow 和 Curl。這適用於任何儲存格魔術（而不僅僅是上述提及的那些），並且僅影響 Jupyter Notebook 的建立。

警告

最佳做法是確保 .py 和 .html 檔案與 .ipynb 檔案盡可能地匹配。此功能僅應在相關程式碼打算由最終使用者執行時使用。

不執行範例來建置#

Sphinx-Gallery 可以解析您所有的範例，並在不執行任何腳本的情況下建置圖庫。這僅用於加速圖庫的可視化過程，以及它在您的網站上顯示時所佔用的空間大小，或者您能想到的任何用途。為了實現這一點，您需要在建置過程中傳遞 `no plot` 選項，方法是修改您的 Makefile，如下所示：

html-noplot:
    $(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
    @echo
    @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

請記住，對於 Makefile 來說，空白字元很重要，縮排是使用 Tab 字元，而不是空格字元。

或者，您可以將 plot_gallery 選項新增到您的 conf.py 檔案內的 sphinx_gallery_conf 字典中，將其設為預設值：

sphinx_gallery_conf = {
    ...
    'plot_gallery': 'False',
}

最高的優先權始終給予 sphinx-build 命令的 -D 旗標。

注意

如果在您的 Makefile 中新增 html-noplot，您還需要在您的 conf.py 檔案內的 sphinx_gallery_conf 字典中，明確設定 plot_gallery 的預設值，以避免出現 sphinx 設定警告。

壓縮圖片#

當寫入 PNG 檔案（預設的 scraper 格式）時，可以將 Sphinx-Gallery 設定為使用 optipng 來優化 PNG 檔案大小。通常，這可以將檔案大小減少約 50%，從而縮短圖庫的載入時間。但是，這可能會增加建置時間。允許的值為 'images' 和 'thumbnails'，或元組/清單（以同時優化兩者），例如：

sphinx_gallery_conf = {
    ...
    'compress_images': ('images', 'thumbnails'),
}

預設值為 () (不優化)，如果請求優化但 optipng 不可用，則會發出警告。您也可以傳遞額外的命令列選項（以 '-' 開頭），例如，為了減少優化但加快建置時間，您可以這樣做：

sphinx_gallery_conf = {
    ...
    'compress_images': ('images', 'thumbnails', '-o1'),
}

有關選項的完整清單，請參閱 $ optipng --help。

多解析度圖片#

網頁瀏覽器允許在 <img> 標籤中使用 srcset 參數，讓瀏覽器支援 適用於高 DPI/Retina 顯示器的響應式解析度圖片。Sphinx Gallery 通過 image_srcset 參數支援此功能：

sphinx_gallery_conf = {
    ...
    'image_srcset': ["2x"],
}

這會在正常圖形 dpi（通常為 100 dpi）下儲存一個 1x 圖片，並以兩倍密度（例如 200 dpi）儲存一個 2x 版本。預設值是不額外產生圖片 ('image_srcset': [])，如果需要，您可以將其他解析度指定為清單： ["2x", "1.5x"]。

matplotlib scraper 會在 rst 檔案中建立一個自訂的圖片指令 image-sg：

.. image-sg:: /examples/images/sphx_glr_test_001.png
    :alt: test
    :srcset: /examples/images/sphx_glr_test_001.png, /examples/images/sphx_glr_test_001_2_0x.png 2.0x
    :class: sphx-glr-single-img

這會由自訂指令轉換為 html，如下所示：

.. <img src="../_images/sphx_glr_test_001.png" alt="test", class="sphx-glr-single-img",
    srcset="../_images/sphx_glr_test_001.png, ../_images/sphx_glr_test_001_2_0x.png 2.0x>

這會導致網站變大，但支援 srcset 標籤的客戶端只會下載適當大小的圖片。

請注意，.. image-sg 指令目前會忽略其他 .. image 指令標籤，例如 width、height 和 align。它也僅適用於 *html* 和 *latex* 建置器。

圖片 scraper#

圖片 scraper 是一種外掛程式，可讓 Sphinx-Gallery 偵測在執行範例期間產生的圖片，然後將它們嵌入到文件中。可以通過將 scraper 名稱附加到您的 Sphinx-Gallery 設定中的 'image_scrapers' 元組來啟用 scraper。例如，若要抓取 matplotlib 圖片，您可以執行以下操作：

sphinx_gallery_conf = {
    ...
    'image_scrapers': ('matplotlib',),
}

預設值為 'image_scrapers': ('matplotlib',)，它只會抓取 Matplotlib 圖片。請注意，這包括任何由基於 Matplotlib 的套件（例如 Seaborn 或 Yellowbrick）產生的圖片。

Matplotlib 動畫#

如果您希望將 matplotlib.animation.Animation 作為動畫而不是動畫圖形的單個靜態圖片嵌入，您應該使用 matplotlib_animations 設定。它接受一個布林值，表示是否應啟用動畫，或接受格式為 (enabled: bool, format: str) 的元組。

sphinx_gallery_conf = {
    ...
    'matplotlib_animations': (True, 'mp4'),
}

matplotlib_animations 預設為 False。

Matplotlib 支援的任何動畫檔案格式都是允許的。如果未指定格式（即，它是單個布林值），或是 *None*，則格式由 rcParams['animation.html'] 和您的 matplotlib rcParams 中的相關選項決定。這表示可以在您的程式碼區塊內設定它，但請注意，Sphinx-Gallery 會在每次執行範例檔案之前重設 Matplotib 預設值（請參閱 重設模組）。

如果格式為 'html5' 或 'jshtml'，則動畫實際上會嵌入到產生的 HTML 檔案中。否則，動畫會儲存到外部檔案中，從而減少產生的 ReST 檔案的大小。如果您要求儲存到外部檔案的格式，您需要在您的環境中安裝 sphinxcontrib-video 擴充功能。

請注意，雖然 matplotlib_animations 允許您全域設定 rcParams['animation.html']，但在程式碼區塊內設定它會覆寫全域設定。

也建議確保 "FFmpeg" 或 "imagemagick" 可用作 writer。使用 matplotlib.animation.ImageMagickWriter.isAvailable() 或 matplotlib.animation.FFMpegWriter.isAvailable() 來檢查。我們建議使用 FFMpeg writer，除非您使用 Matplotlib <3.3.1。

支援以下 scraper：

  • matplotlib

    Sphinx-Gallery 通過字串 'matplotlib' 維護一個用於 matplotlib 圖形的 scraper。

  • PyVista

    PyVista 維護一個 scraper（適用於 PyVista >= 0.20.3），由字串 'pyvista' 啟用。

  • PyGMT

    有關如何與 Sphinx-Gallery 整合的詳細資訊，請參閱 他們的網站。

  • qtgallery

    此程式庫提供 Qt 視窗的 scraper。有關如何與 Sphinx-Gallery 整合的說明，請參閱 他們的儲存庫。

您可以為上述列出的套件之外的套件產生的圖片編寫自訂的 scraper。這是通過編寫自己的 Python 函數來定義如何偵測和檢索任意套件產生的圖片來完成的。有關說明，請參閱 編寫自訂圖片 scraper。如果您想出一個對一般使用有用的實作（例如，繪圖程式庫的自訂 scraper），請隨時將其新增到上面的清單中（請參閱此處的討論 這裡）！

使用多個程式碼區塊來建立單個圖形#

預設情況下，圖片會在範例中的每個程式碼區塊之後進行抓取。因此，以下內容會產生兩個圖，每個程式碼區塊一個圖：

# %%
# This first code block produces a plot with two lines

import matplotlib.pyplot as plt
plt.plot([1, 0])
plt.plot([0, 1])

# %%
# This second code block produces a plot with one line

plt.plot([2, 2])
plt.show()

但是，有時可以使用多個程式碼區塊來建立單個圖形，特別是當圖形需要大量命令，並且這些命令可以從與文字區塊交錯中受益時。可選旗標 sphinx_gallery_defer_figures 可以作為註解插入程式碼區塊中的任何位置，以將圖片的抓取延遲到下一個程式碼區塊（如果需要，可以在下一個程式碼區塊中進一步延遲）。以下內容只會產生一個圖：

# %%
# This first code block does not produce any plot

import matplotlib.pyplot as plt
plt.plot([1, 0])
plt.plot([0, 1])
# sphinx_gallery_defer_figures

# %%
# This second code block produces a plot with three lines

plt.plot([2, 2])
plt.show()

控制來自同一程式碼區塊的多個圖形的佈局#

預設情況下，從同一程式碼區塊產生的多個圖形會並排堆疊。特別是對於寬圖形，這可能會導致圖片大幅縮小，失去其清晰度。可以使用兩個可選變數來控制此行為：

  • 檔案範圍的 sphinx_gallery_multi_image 變數

  • 程式碼區塊特定的 sphinx_gallery_multi_image_block 變數

預設行為是將這些變數視為設定為 "multi"，這會導致圖形並排堆疊。將這些變數設定為 "single" 將允許從程式碼區塊產生的圖形顯示為單一欄。

例如，新增：

# sphinx_gallery_multi_image = "single"

在範例檔案中的某處，將導致顯示所有程式碼區塊中產生多個圖形的圖片，這些圖片會顯示在單一欄中。

或者，新增：

# sphinx_gallery_multi_image_block = "single"

到程式碼區塊，將導致僅該程式碼區塊的多個圖形顯示在單一欄中。

反之，如果為整個檔案設定 sphinx_gallery_multi_image = "single"，則新增 sphinx_gallery_multi_image_block = "multi" 可以還原單一程式碼區塊的預設行為。

有關此功能的示範，請參閱範例 強制將圖形顯示在個別的行上。

隱藏程式碼行#

通常，Sphinx-Gallery 在建置 HTML 和 iPython 筆記本時會呈現每一行 Python 程式碼。這通常是可取的，因為我們希望確保 Python 原始程式檔、HTML 和 iPython 筆記本都執行相同的操作。

然而，有時我們需要執行某些 Python 程式碼，但不希望它們出現在任何使用者介面的文件中。例如，假設我們想加入一些 assert 陳述式來驗證文件是否成功建置，但不希望這些陳述式顯示給使用者。我們可以利用 sphinx_gallery_start_ignore 和 sphinx_gallery_end_ignore 標記來達成這個目的。

model.compile()
# sphinx_gallery_start_ignore
assert len(model.layers) == 5
assert model.count_params() == 219058
# sphinx_gallery_end_ignore
model.fit()

當 HTML 或 iPython 筆記本建置時，這個程式碼區塊將會顯示為：

model.compile()
model.fit()

sphinx_gallery_start_ignore 和 sphinx_gallery_end_ignore 標記可以用在任何程式碼區塊中，而且在同一個區塊中可以使用多對標記。每個起始標記都必須有一個對應的結束標記，否則在文件生成期間會引發錯誤。這些標記和它們之間的程式碼總是會被移除，無論 remove_config_comments 設定為何。

請注意，被忽略程式碼的任何輸出仍然會被捕獲。

警告

這個標記應該謹慎使用，因為它會讓 .py 原始碼檔案與生成的 .html 和 .ipynb 檔案之間的對應關係降低。當可以使用其他能保留這種關係的方法時，使用這個標記是不好的做法。

產生虛擬圖片#

為了快速視覺化您的圖庫，尤其是在撰寫過程中，Sphinx-Gallery 允許您在不執行程式碼的情況下建置圖庫（請參閱 不執行範例進行建置 和 檔案名稱/忽略模式）。然而，如果您手動撰寫了指向自動生成圖片的連結，這可能會導致關於遺失圖片檔案的警告。為了避免這些警告，您可以告訴 Sphinx-Gallery 為範例建立一些虛擬圖片。

例如，您可能有一個範例（'my_example.py'）會生成 2 張圖片，然後您在其他地方手動參考這些圖片，例如：

Below is a great figure:

.. figure:: ../auto_examples/images/sphx_glr_my_example_001.png

Here is another one:

.. figure:: ../auto_examples/images/sphx_glr_my_example_002.png

為了避免在不執行程式碼的情況下建置時出現遺失圖片檔案的警告，您可以將以下內容添加到範例檔案中：

# sphinx_gallery_dummy_images=2

這將導致 Sphinx-Gallery 生成 2 張虛擬圖片，其命名慣例與執行建置時生成的圖片相同，並儲存在相同的位置。如果已經存在圖片（例如，來自先前的建置執行），則不會生成虛擬圖片，因此不會被覆寫。

注意

這個設定**僅**在範例設定為不執行時才有效（也就是說，plot_gallery 為 'False'，範例位於 ignore_pattern 中，或者範例不在 filename_pattern 中 - 請參閱 檔案名稱/忽略模式）。這表示當您切換為執行建置圖庫時，您不需要移除範例中的任何 sphinx_gallery_dummy_images 行。

重設模組#

通常，您希望「重設」您的視覺化套件的行為，以確保在一個範例中對繪圖行為所做的任何變更不會傳播到其他範例。

預設情況下，在每個範例檔案執行之前，Sphinx-Gallery 會重設 matplotlib（透過使用 matplotlib.pyplot.rcdefaults() 並重新載入填充單位註冊表的子模組）和 seaborn（透過嘗試從 sys.modules 卸載模組）。這相當於以下設定：

sphinx_gallery_conf = {
    ...
    'reset_modules': ('matplotlib', 'seaborn'),
}

目前，Sphinx-Gallery 原生支援重設 matplotlib 和 seaborn。然而，您也可以將自己的自訂函式添加到這個元組中，以便為其他視覺化函式庫定義重設行為。

若要執行此操作，請依照 每次範例執行前重設 中的指示。

重設模組的順序#

預設情況下，Sphinx-Gallery 會在每個範例執行之前重設模組。reset_modules_order 的選項為 before（預設）、after 和 both。如果 Sphinx-Gallery 中最後一個執行的範例修改了模組，建議使用 after 或 both，以避免將修改過的模組洩漏到 Sphinx 建置過程的其他部分。例如，在設定中將 reset_modules_order 設定為 both：

sphinx_gallery_conf = {
    ...
    'reset_modules_order': 'both',
}

可以建構自訂函式，使其根據是在範例之前還是之後呼叫而具有自訂功能。請參閱 每次範例執行前重設 以取得更多資訊。

啟用範例推薦系統#

可以設定 Sphinx-Gallery，為範例展示廳產生基於內容的推薦。相關範例的清單是透過計算其文字內容的 TF-IDF 空間中最接近的範例自動產生。僅使用單一展示廳（包括其子展示廳）中的範例來計算最接近的範例。然後，最相似的內容會以一組縮圖顯示在每個範例的底部。

可以透過將 enable 設定為 True 來啟用推薦系統。若要設定它，請將字典傳遞至 sphinx_gallery_conf，例如：

sphinx_gallery_conf = {
    ...
    "recommender": {"enable": True, "n_examples": 5, "min_df": 3, "max_df": 0.9},
}

唯一必要的參數是 enable。如果未指定任何其他參數，則會使用預設值。以下是每個欄位的更完整說明：

enable (類型：布林值，預設值：False)

是否在範例展示廳內產生推薦。啟用此功能需要將 numpy 新增至相依性。

n_examples (類型：整數，預設值：5)

要顯示的最相關範例數。

min_df (類型：範圍 [0.0, 1.0] 中的浮點數 | 整數，預設值：3)

在建置詞彙表時，忽略文件頻率嚴格低於給定閾值的詞彙。如果為浮點數，則參數表示文件的比例；如果為整數，則表示絕對計數。此值在文獻中也稱為截止值。

max_df (類型：範圍 [0.0, 1.0] 中的浮點數 | 整數，預設值：0.9)

在建置詞彙表時，忽略文件頻率嚴格高於給定閾值的詞彙。如果為浮點數，則參數表示文件的比例；如果為整數，則表示絕對計數。

rubric_header (類型：字串，預設值：「相關範例」)

可自訂的標題。可以編輯為更具描述性的文字，或新增外部連結，例如，連結到 Sphinx-Gallery 文件中推薦系統的 API 文件。

使用者可以自訂參數 min_df 和 max_df，以修剪非常罕見/非常常見的單字。這可能會提高推薦品質，但更重要的是，它節省了一些會浪費在非資訊性權杖上的計算資源。

目前僅為 .py 檔案計算範例推薦。

最小回報時間#

預設情況下，Sphinx-Gallery 會記錄每個指令碼的執行時間，並將其嵌入 HTML 輸出中。如果您的範例大多執行快速，您可能不需要此資訊。

可以將 min_reported_time 參數設定為秒數。執行速度快於該數量的指令碼的持續時間將不會記錄或嵌入到 HTML 輸出中。

寫入計算時間#

如果您想從所有展示廳輸出中省略計算時間，請設定為 False。這有助於建立可重現的建置。預設值為 True，除非設定了 SOURCE_DATE_EPOCH 環境變數。

顯示記憶體消耗量#

如果安裝了 memory_profiler，Sphinx-Gallery 可以使用它來報告範例執行期間的峰值記憶體。安裝 memory_profiler 後，您可以執行以下操作：

sphinx_gallery_conf = {
    ...
    'show_memory': True,
}

也可以使用您自己的自訂記憶體回報器，例如，如果您想查看 GPU 記憶體。在這種情況下，show_memory 必須是可呼叫的，它接受要呼叫的單一函式 (也就是說，內部產生以執行個別指令碼程式碼區塊的函式)，並傳回包含兩個元素的元組：

  1. 執行函式時使用的記憶體量 (以 MiB 為單位)，以及

  2. 函式輸出

一個始終回報使用 0 記憶體的版本會是

sphinx_gallery_conf = {
    ...
    'show_memory': lambda func: (0., func()),
}

顯示簽名#

預設情況下，Sphinx-Gallery 會在產生的輸出中寫入 產生者：… 通知。

可以使用 show_signature 參數停用它。

控制捕捉的輸出內容#

注意

設定 capture_repr 為空元組 (也就是說，capture_repr: ())，以返回 v0.5.0 版之前的輸出捕捉行為。

capture_repr 設定允許使用者控制在執行範例 .py 檔案時捕捉的輸出內容，並隨後併入建置的文件中。導向標準輸出的資料始終會被捕捉。每個程式碼區塊的最後一個陳述式的值 (如果它是運算式) 也可以被捕捉。這可以透過在 capture_repr 元組中提供要捕捉的「表示」方法名稱 (依偏好順序) 來完成。目前支援的表示方法如下：

  • __repr__ - 傳回物件的官方字串表示。這是當您的 Python Shell 評估運算式時傳回的內容。

  • __str__ - 傳回包含物件的易於列印表示的字串。這是當您 print() 物件或將其傳遞給 format() 時使用的內容。

  • _repr_html_ - 傳回物件的 HTML 版本。此方法僅存在於某些物件中，例如，pandas 資料框架。

可以透過 capture_repr 設定來全域控制輸出捕捉，也可以透過在範例檔案中新增註解來逐個檔案控制，這會覆寫任何全域設定

# sphinx_gallery_capture_repr = ()

預設設定為

sphinx_gallery_conf = {
    ...
    'capture_repr': ('_repr_html_', '__repr__'),
}

使用預設設定，Sphinx-Gallery 會先嘗試捕捉程式碼區塊最後一個陳述式的 _repr_html_，如果它是運算式。如果此方法不存在於運算式中，則會捕捉元組中的第二個「表示」方法，__repr__。如果 __repr__ 也沒有存在 (對於非使用者定義的物件不太可能)，則不會捕捉任何內容。導向標準輸出的資料始終會被捕捉。如需數個範例，請參閱捕捉輸出表示。

若要僅捕捉導向標準輸出的資料，請將 'capture_repr' 設定為空元組：'capture_repr': ()。這會模擬 v0.5.0 之前的 Sphinx-Gallery 行為。

從另一個角度來看，以下列程式碼區塊為例

print('Hello world')
a=2
a  # this is an expression

對於每個 capture_repr 設定，都會捕捉 'Hello world'，因為這是導向標準輸出的。此外，

  • 如果 capture_repr 為空元組，則不會捕捉任何其他內容。

  • 如果 capture_repr 為 ('__repr__')，則 2 也會被捕獲。

  • 如果 capture_repr 為 ('_repr_html_', '__repr__') (預設值)，Sphinx-Gallery 會先嘗試捕獲 _repr_html_。由於 a 沒有這個屬性，它會接著嘗試捕獲 __repr__。a 確實有 __repr__ 方法，因此在這種情況下，2 也會被捕獲。

Matplotlib 注意事項：如果 'capture_repr' 元組包含 '__repr__' 和/或 '__str__'，則以 Matplotlib 函式呼叫作為最後一個表達式的程式碼區塊，通常會在產生的文件中顯示黃色的輸出框以及圖形。這是因為 Matplotlib 函式呼叫通常會回傳值，並在標準輸出中建立/修改圖表。例如，matplotlib.plot() 會回傳代表繪製資料的 Line2D 物件列表。這個列表有 __repr__ 和 __str__ 方法，因此它們會被捕獲。您可以透過以下方式防止這種情況：

  • 將（最後一個）繪圖函式指定給一個暫時變數。例如：

    import matplotlib.pyplot as plt

_ = plt.plot([1, 2, 3, 4], [1, 4, 9, 16])

  • 在您的程式碼區塊的結尾加入 plt.show()（它不會回傳任何值）。例如：

    import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4], [1, 4, 9, 16])
plt.show()

如果 'capture_repr' 是一個空元組，或者不包含 __repr__ 或 __str__，就不會出現不需要的字串輸出。

防止捕獲特定類別#

如果您希望捕獲每個程式碼區塊最後一個表達式的表示形式，除非最後一個表達式是某種類型，您可以使用 'ignore_repr_types'。'ignore_repr_types' 預設為空原始字串 (r'')，表示不忽略任何類型。若要排除特定類型不被捕獲，可以將 'ignore_repr_types' 設定為符合要排除的類型名稱的正規表示式。

例如，以下組態會捕獲每個程式碼區塊最後一個表達式的 __repr__，除非最後一個表達式的 type() 名稱包含字串 'matplotlib.text' 或 'matplotlib.axes'。這將防止捕獲所有 'matplotlib.text' 的子類別，例如 'matplotlib.text.Annotation'、'matplotlib.text.OffsetFrom' 等類型的表達式。同樣地，'matplotlib.axes' 的子類別（例如 'matplotlib.axes.Axes'、'matplotlib.axes.Axes.plot' 等）也不會被捕獲。

sphinx_gallery_conf = {
    ...
    'capture_repr': ('__repr__'),
    'ignore_repr_types': r'matplotlib\.(text|axes)',
}

手動傳遞檔案#

預設情況下，Sphinx-Gallery 會建立所有寫入 sphinx-build 目錄的檔案，方法是從展示區來源中的 *.py 產生 rst 和圖像，或從展示區來源中的 GALLERY_HEADER.rst (或為向後相容性使用 README.[rst/txt]) 建立 index.rst。但是，有時需要將檔案從展示區來源傳遞到 sphinx-build。例如，您可能想要傳遞展示區引用的影像，但它本身不會產生。您也可能想要將原始 rst 從展示區來源傳遞到 sphinx-build，因為該材料在主題上適合您的展示區，但以 rst 撰寫更容易。為此，您可以在 sphinx_gallery_conf 中設定 copyfile_regex。以下會複製 rst 檔案。

sphinx_gallery_conf = {
    ...
   'copyfile_regex': r'.*\.rst',
}

請注意，如果您複製 rst 檔案，例如，您有責任確保它們位於您文件中某處的 sphinx toctree 中。當然，您可以將 toctree 新增到您的 GALLERY_HEADER.rst 中。

手動傳遞 index.rst#

您可以繞過 Sphinx-Gallery 自動從展示區目錄或巢狀子展示區目錄中的 GALLERY_HEADER.rst 建立 index.rst。如果您的 copyfile_regex 包含 index.rst，並且您在展示區來源（即 examples_dirs 目錄）中有一個 index.rst，則 Sphinx-Gallery 會改用它，而不會為該展示區或其任何子展示區建立索引檔案。如果您傳遞自己的 index.rst 檔案，您有責任在該索引中（或在您的 Sphinx 文件中的其他位置）加入您自己的 Sphinx toctree，其中包含該目錄中的任何展示區項目或其他檔案。您還有責任為該展示區的子展示區加入任何必要的 index.rst 檔案。

顯示 API 用法#

未使用 API 條目以及每個 API 條目所使用的範例的圖表和文件，會在 Sphinx 輸出目錄下的 sg_api_usage.html 中產生。請參閱Sphinx-Gallery API 使用情況文件和圖表以了解範例。在大型專案中，會有許多模組，而且由於每個模組都會產生 API 使用情況的圖表，因此可能會使用大量資源，所以 show_api_usage 預設會設定為 'unused'。所有未使用的 API 條目都會顯示在一個圖表中，因此對於大型專案來說，這種方式的擴展性更好。將 show_api_usage 設定為 True 將會為每個模組製作一個圖表，顯示所有與其使用的範例相關聯的 API 條目。如果您想了解特定模組，這對於建立要查看哪些範例的地圖可能很有幫助。將 show_api_usage 設定為 False 將不會製作任何關於 API 使用情況的圖表或文件。請注意，製作未使用和已使用的 API 條目圖表需要 graphviz。

忽略 API 條目#

預設情況下，api_usage_ignore='.*__.*__' 會忽略符合此正規表示式的檔案，並在範例圖庫中記錄和繪製 API 條目的使用情況。可以修改此正規表示式以忽略任何不應考慮的檔案類型。預設的正規表示式會忽略像 __len__() 這樣的函數，如果它們在範例中使用，可能不希望記錄它們。

本頁內容