Sphinx-Gallery 入门#

创建基本画廊#

本节描述如何使用 Sphinx 扩展 Sphinx-Gallery 为您的示例设置基本画廊，它将执行以下操作

自动从您的 .py 示例文件中生成 Sphinx reST。生成的 reST 的渲染将为用户提供每个示例的 .ipynb (Jupyter 笔记本) 和 .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 目录具有特定的结构，我们将在下面介绍。

构建示例文件夹#

为了使 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 脚本：当您构建 HTML 文档时将处理的 Python 脚本集合。有关如何构建这些包含嵌入式 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 笔记本版本。
.py - 允许用户下载示例的 .py 版本。
.py.md5 - .py 文件的 md5 哈希值，用于确定文件是否进行了更改，以及是否需要生成新的输出文件。
.codeobj.json - 用于识别函数名称以及它们所属的模块（有关更多详细信息，请参见识别脚本中的函数名称）

此外，还将生成两个包含所有 .ipynb 和 .py 文件的压缩 .zip 文件，以及一个包含所有执行时间的根级 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 构建器，但对该功能的支持大多未经测试，结果可能会有所不同。