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)

设置下载和启动器链接的获取器。

获取器被添加到 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) – 文档字符串所属对象的类型。为“module”、“class”、“exception”、“function”、“method”、“attribute”之一。

• name – 对象的完全限定名称。

• obj – 对象本身。

• options – 传递给指令的选项：一个具有继承属性的对象，继承的成员、未记录的成员、显示继承和 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 – 当前正在解析的文档的 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” 可调用对象，它返回一个空列表。