配置#

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 警告，你可以在你的 conf.py 文件中添加以下内容

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 通过使用 md5(str(obj).encode()).hexdigest() 在 sphinx/builders/html.py 中检查 config 值，来确定构建环境是否已更改，以及是否应重新编写所有文档。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 指令，方便您轻松地将缩减版的 Gallery 添加到您的 Sphinx 文档 .rst 文件中。因此，minigallery 指令支持传递以下任何内容的列表（空格分隔）：

要使用对象名称，您必须启用反向引用生成，有关详细信息，请参见 为 API 文档添加迷你画廊。如果未启用反向引用生成，则 MiniGallery 指令中的对象条目将被忽略，所有条目将被视为路径式字符串或 glob 样式的路径式字符串。有关详细信息，请参见 使用文件路径创建迷你画廊。

为 API 文档添加迷你画廊#

Sphinx-Gallery 可以为指定模块中的对象生成迷你画廊，其中包含所有满足以下条件的示例：

  1. 在代码中使用该函数/方法/属性/对象或实例化该类（称为隐式反向引用），或者

  2. 使用 sphinx 标记 :func: / :meth: / :attr: / :obj: / :class: 在文本块中引用该函数/方法/属性/对象/类。如果您已在 conf.py 中将 default_role 设置为这些角色中的任何一个，则可以省略此角色标记（称为显式反向引用）。

这使您可以将对象的完全限定名（例如，函数、方法、属性、类）传递给 minigallery 指令，以添加与该对象相关的所有示例的迷你画廊。这在 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 中列出的模块。请注意，将为所有对象生成反向引用文件。任何不在任何示例中使用的对象都将有一个空文件，以防止在 autodoc 解析期间出现包含错误。

backreferences_dir 应该是一个字符串或 pathlib.Path 对象，该对象相对于 conf.py 文件，或者为 None。默认情况下为 None。

有时，有些函数几乎在给定模块的每个示例中都被使用，例如 Matplotlib 中的 pyplot.show 或 pyplot.subplots 函数，因此大量通常是虚假的示例将链接到这些函数。为了防止这种情况，您可以通过将它们包含在 exclude_implicit_doc 中的正则表达式中来排除某些对象的隐式反向引用。以下设置将排除所有隐式反向引用，以便仅为在文档块中由 Sphinx 标记显式提到的对象创建示例画廊：{'.*'}。要排除上面提到的函数，您需要使用 {r'pyplot\.show', r'pyplot\.subplots'}（请注意转义以匹配点而不是任何字符，如果名称是明确的，您也可以写 pyplot.show 或只写 show）。

使用文件路径创建迷你画廊#

有时您可能想要使用没有共同函数的文件（例如一组教程）显式创建 mini-gallery。因此，minigallery 指令还支持传入：

  • sphinx 画廊示例文件的路径式字符串（相对于 conf.py）

  • Sphinx-Gallery 示例文件的 glob 样式路径式字符串（相对于 conf.py）

例如，下面的 rst 添加了所有使用特定函数 numpy.exp 的示例、示例 examples/plot_sin_.py 以及所有与字符串 /examples/plot_4* 匹配的文件的缩减版 Gallery：

.. minigallery::
    :add-heading:

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

列出多个项目会将所有示例合并到一个迷你画廊中。只有当文件存在，或者项目实际上在示例中被使用或引用时，才会显示迷你画廊。如果缩略图对应于多个对象名称或一个对象名称和文件/glob 输入，则缩略图也可能重复。

使用多个对象之一的示例#

入门示例 - 绘制正弦函数

入门示例 - 绘制正弦函数

选择缩略图

选择缩略图

提供缩略图

提供缩略图

绘制指数函数

绘制指数函数

选择缩略图

选择缩略图

识别脚本中的函数名称

识别脚本中的函数名称

您也可以在指令主体中提供项目列表：

.. minigallery::
    :add-heading:

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

如果未提供字符串参数，则当仅列出单个项目时，add-heading 选项会为迷你画廊添加标题，默认标题为：

“使用{完整限定的对象名称}的示例”

对于具有多个项目的画廊，建议指定自定义标题消息，因为否则默认消息为：

“多个对象之一的示例”。

上面显示的示例迷你画廊使用默认标题级别 ^。可以使用 heading-level 选项更改此选项，该选项接受单个字符（例如，-）。

您也可以将输入作为空格分隔的参数列表传递给 minigallery 指令：

.. 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 文件。要创建一个名为 junit-result.xml 的文件（例如在 /build 输出目录中），请设置配置键（路径相对于 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 笔记本收集到压缩文件中，这些压缩文件可以在每个画廊的底部下载。要禁用此行为，请在您的 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 文件，注释应位于文档字符串下方（最好是在代码块中，请参阅 删除配置注释）。

例如，以下定义了使用 _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）的缩略图，以了解此功能的示例。

使笔记本中的单元格魔法可执行#

教程中通常会包含用户需要复制/粘贴到终端中的 bash 代码。构建文档时不应运行此代码，因为用户已经在其环境中安装了这些依赖项。因此，它们通常作为文本内的代码块编写

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

这对于 .py 和 .html 文件效果很好，但在渲染为 Jupyter 笔记本时会导致问题。下载的 .ipynb 文件将没有安装这些依赖项，并且在运行 bash 代码之前将无法正常工作。

为了解决此问题，我们可以在 conf.py 中设置 promote_jupyter_magic 标志

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

如果此标志为 True，那么在构建 Jupyter 笔记本时，任何以 Jupyter 单元格魔法（例如 %%bash 或 %%writefile）开头的代码块将被转换为可运行的代码块。

对于我们之前的示例，我们可以将 Markdown 文本更改为

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

这意味着 TensorFlow 和 Curl 将在运行 Jupyter 笔记本时自动安装。这适用于任何单元格魔法（不只是上面提到的那些），并且仅影响 Jupyter 笔记本的创建。

警告

最佳实践是确保 .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，空格很重要，缩进使用的是制表符，而不是空格。

或者，您可以将 plot_gallery 选项添加到 conf.py 中的 sphinx_gallery_conf 字典中，将其设置为默认值

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

-D 标志的优先级始终最高 sphinx-build 命令。

注意

如果将 html-noplot 添加到 Makefile 中，您还需要在 conf.py 文件中的 sphinx_gallery_conf 字典中显式设置 plot_gallery 的默认值，以避免出现 Sphinx 配置警告。

压缩图像#

在编写 PNG 文件（默认的抓取器格式）时，可以配置 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。

多分辨率图像#

Web 浏览器允许在 <img> 标签中使用 srcset 参数，使浏览器支持 响应式分辨率图像，以适应高分辨率/视网膜显示屏。Sphinx Gallery 通过 image_srcset 参数支持此功能。

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

它会保存一个以正常图像 dpi（通常为 100 dpi）生成的 1x 图像，以及一个以两倍密度（例如 200 dpi）生成的 2x 版本。默认情况下不生成额外的图像 ('image_srcset': [])，您也可以根据需要将其他分辨率指定为列表：["2x", "1.5x"]。

Matplotlib 刮取程序会在 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 生成器。

图像刮取程序#

图像刮取程序是 Sphinx-Gallery 的插件，允许它检测在执行示例期间产生的图像，并将它们嵌入到文档中。可以通过在 Sphinx-Gallery 配置中的 'image_scrapers' 元组中添加刮取程序名称来激活刮取程序。例如，要刮取 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 编写器，除非您使用的是 Matplotlib <3.3.1。

支持以下刮取程序：

  • matplotlib

    Sphinx-Gallery 通过字符串 'matplotlib' 为 matplotlib 图形维护一个刮取程序。

  • PyVista

    PyVista 通过字符串 'pyvista' 维护一个刮取程序（适用于 PyVista >= 0.20.3）。

  • PyGMT

    有关如何与 Sphinx-Gallery 集成的更多信息，请参见 他们的网站。

  • qtgallery

    该库提供了一个用于 Qt 窗口的刮取程序。有关如何与 Sphinx-Gallery 集成的说明，请参见 他们的存储库。

可以为在上面列出的软件包之外生成的图像编写自定义刮取程序。这可以通过编写您自己的 Python 函数来实现，该函数定义如何检测和检索由任意软件包生成的图像。有关说明，请参见 编写自定义图像刮取程序。如果您想出一种对一般用途有用的实现（例如，一个用于绘图库的自定义刮取程序），请随时将其添加到上面的列表中（参见讨论 此处）！

使用多个代码块创建单个图形#

默认情况下，图像是在示例中的每个代码块之后刮取的。因此，以下操作将生成两个图形，每个代码块一个图形：

# %%
# 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（类型：bool，默认值：False）

是否在示例画廊中生成推荐。启用此功能需要将 numpy 添加到依赖项中。

n_examples（类型：int，默认值：5）

要显示的最相关示例的数量。

min_df（类型：范围 [0.0, 1.0] 中的 float | int，默认值：3）

在构建词汇表时，忽略文档频率严格低于给定阈值的术语。如果为 float，则参数表示文档的比例，整数表示绝对计数。此值在文献中也被称为截止值。

max_df（类型：范围 [0.0, 1.0] 中的 float | int，默认值：0.9）

在构建词汇表时，忽略文档频率严格高于给定阈值的术语。如果为 float，则参数表示文档的比例，整数表示绝对计数。

rubric_header（类型：str，默认值：“Related examples”）

可定制的评分规则标题。它可以编辑为更具描述性的文本或添加外部链接，例如指向 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 会在生成的输出中写入 Generated by … 通知。

参数 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

'Hello world' 将针对所有 capture_repr 设置进行捕获，因为这会定向到标准输出。此外，

  • 如果 capture_repr 是一个空元组，则不会捕获任何其他内容。

  • 如果 capture_repr 是 ('__repr__')，则还会捕获 2。

  • 如果 capture_repr 是 ('_repr_html_', '__repr__')（默认设置），Sphinx-Gallery 会首先尝试捕获 _repr_html_。由于 a 不存在此方法，因此它会尝试捕获 __repr__。方法 __repr__ 存在于 a 中，因此在这种情况下，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'')，这意味着不忽略任何类型。要排除特定类型(s)不进行捕获，可以将 'ignore_repr_types' 设置为与要排除的类型(s)的名称相匹配的正则表达式。

例如，以下配置将捕获每个代码块最后一个表达式的 __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 中。当然，您可以在您的 GALLERY_HEADER.rst 中添加一个 toctree。

手动传递 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__() 这样的函数，可能不希望记录它们是否在示例中使用。

本页内容