sphinx_gallery.gen_gallery

Sphinx-Gallery 產生器。

將 Sphinx-Gallery 連接到 Sphinx，以便在建立文件時產生範例集。

函式

sphinx_gallery.gen_gallery.clean_api_usage_files(app, exception)

移除 API 使用 .dot 檔案。

連線到 ‘build-finished’ 事件。

sphinx_gallery.gen_gallery.fill_gallery_conf_defaults(app, config, check_keys=True)

檢查 sphinx-gallery 設定並設定其預設值。

這會在 config-inited 早期被呼叫，以便其餘程式碼可以執行諸如 sphinx_gallery_conf['binder']['use_jupyter_lab'] 之類的操作，即使索引鍵沒有在 conf.py 中明確設定。

sphinx_gallery.gen_gallery.generate_gallery_rst(app)

產生主要的範例集 reStructuredText。

填寫 Sphinx-Gallery 設定並掃描範例目錄（最多一層子目錄深度）以產生範例 reST 檔案。

迭代每個範例目錄及其任何具有標頭/索引檔案的子目錄（建立子章節）。產生範例集的 ReST 檔案和 index.rst 檔案。

如果 nested_sections=True，我們將為所有子目錄產生 index.rst 檔案，其中包括連結到所有子目錄範例的 toctree。根範例目錄 index.rst 檔案將依序包含，

• 根範例集標頭然後是縮圖，

• toctree 連結根範例集中的所有範例，

• 子章節標頭，後接所有子章節的子章節縮圖，

• 第二個最終 toctree，在檔案末尾，連結到所有子章節索引檔案。

如果 nested_sections=True，我們為每個範例目錄產生單一 index.rst 檔案。它將包含根範例集和每個子章節的標頭，每個標頭後接一個連結到根範例集/子章節中每個範例的 toctree。

sphinx_gallery.gen_gallery.get_default_config_value(key)

取得預設設定函式。

sphinx_gallery.gen_gallery.get_subsections(srcdir, examples_dir, gallery_conf, check_for_header=True)

傳回範例集的子章節清單。

參數：

• srcdir (str) – 包含 conf.py 的目錄的絕對路徑

• examples_dir (str) – 相對於 conf.py 的範例目錄路徑

• gallery_conf (Dict[str, Any]) – Sphinx-Gallery 設定字典。

• check_for_header (bool) – 僅傳回包含 GALLERY_HEADER 檔案的子資料夾，預設為 True

傳回：

out – 範例集子章節資料夾名稱的排序清單

傳回類型：

list

sphinx_gallery.gen_gallery.setup(app)

設定 Sphinx-Gallery sphinx 擴充功能。

sphinx_gallery.gen_gallery.setup_module()

為了停止 nosetests 執行上述的 setup() 的駭客方法。

sphinx_gallery.gen_gallery.setup_template_link_getters(app, pagename, templatename, context, doctree)

設定下載和啟動器連結的 getter。

getter 會新增至 sphinx 上下文，以便在範本中使用。

sphinx_gallery.gen_gallery.summarize_failing_examples(app, exception)

收集失敗的範例清單，並使用追溯列印它們。

如果存在失敗的範例，則引發 ValueError。

sphinx_gallery.gen_gallery.touch_empty_backreferences(app, what, name, obj, options, lines)

產生空的向後參考範例檔案。

這可以避免在 autodoc 剖析類別/模組時，如果沒有範例集範例，則會發生包含錯誤/警告。

sphinx_gallery.gen_gallery.update_gallery_conf_builder_inited(app)

在 builder-inited 時更新 sphinx-gallery 設定。

sphinx_gallery.gen_gallery.write_api_entries(app, what, name, obj, options, lines)

將 API 項目寫入 _sg_api_entries 設定。

連線到 autodoc-process-docstring 事件。

參數：

• app – Sphinx 應用程式物件。

• what (str) – docstring 所屬物件的類型。其中一個為 “module”、“class”、“exception”、“function”、“method”、“attribute”。

• name – 物件的完整名稱。

• obj – 物件本身。

• options – 傳遞給指令的選項：一個物件，其屬性包含 inherited_members、undoc_members、show_inheritance 和 no-index，如果 auto 指令中使用了相同名稱的旗標選項，則這些屬性為 true。

• lines – 文件字串的行，請參閱上方。

sphinx_gallery.gen_gallery.write_api_entry_usage(app, docname, source)

撰寫一個 HTML 頁面，描述哪些 API 項目被使用和未使用。

為了僅記錄和繪製 autodoc 使用的 API 項目，我們必須等待 autodoc 完成並掛鉤到 source-read 事件。這會攔截來自 rst 的文字，以便可以修改它。由於我們只觸及了一個空檔案，我們必須添加：1) 一個未使用的所有 API 項目列表，以及每個模組中未使用的 API 項目數量的圖表；以及 2) 一個在範例中使用的 API 項目列表，每個項目都有一個子列表，列出該 API 項目在哪些範例中使用，以及一個將模組中所有 API 項目連接到它們所使用的範例的圖表。

參數：

• app – Sphinx 應用程式物件。

• docname – 目前正在解析的文件名稱。

• source – 一個列表，其單一元素是來源檔案的內容。

sphinx_gallery.gen_gallery.write_computation_times(gallery_conf, target_dir, costs)

將計算時間寫入 sg_execution_times.rst。

參數：

• gallery_conf (Dict[str, Any]) – Sphinx-Gallery 設定字典。

• target_dir (str | None) – 範例 Python 原始檔案所在目錄的路徑。

• costs (List[Dict]) – 計算成本和路徑的字典列表，詳情請參閱 gen_rst.py。

sphinx_gallery.gen_gallery.write_junit_xml(gallery_conf, target_dir, costs)

撰寫範例執行時間、成功和失敗的 JUnit XML 檔案。

參數：

• gallery_conf (Dict[str, Any]) – Sphinx-Gallery 設定字典。

• target_dir (Union[str, pathlib.Path]) – 建置目錄。

• costs (List[Tuple[Tuple[float], str]]) – 計算成本和路徑的字典列表，詳情請參閱 gen_rst.py。

類別

class sphinx_gallery.gen_gallery.DefaultResetArgv

提供預設的 'reset_argv' 可呼叫物件，該物件會傳回空列表。