使用sphinx_gallery.sorting.ExplicitOrder()按照指定顺序排列示例

Sphinx-Gallery是一个可以自动构建示例图片和代码的Python工具，它可以将代码片段转换为Jupyter笔记本并与文档一起展示。Sphinx-Gallery允许开发者在文档中利用示例代码，以便更好地解释和演示特定的功能。

Sphinx-Gallery允许用户对示例代码进行排序，以便按照指定的顺序进行展示。其中一个排序机制是使用sphinx_gallery.sorting.ExplicitOrder()进行排序，它允许用户按照特定的顺序排列示例，并在生成的文档中按照该顺序进行展示。本文将对如何使用ExplicitOrder进行示例排序进行详细说明，并提供一个使用例子。

要开始使用ExplicitOrder进行示例排序，首先需要确保已经安装了Sphinx-Gallery。可以使用以下命令安装Sphinx-Gallery：

pip install sphinx-gallery

接下来，需要在Sphinx的配置文件（通常是conf.py）中添加一些额外的设置，以便启用Sphinx-Gallery和指定示例的排序方法。在conf.py中进行如下设置：

import sphinx_gallery.sorting

sphinx_gallery_conf = {
    'examples_dirs': 'examples',
    'gallery_dirs': 'gallery',
    'within_subsection_order': sphinx_gallery.sorting.ExplicitOrder([
        'example_3',
        'example_1',
        'example_2',
    ])
}

上述代码中，'examples_dirs'和'gallery_dirs'分别指定了示例代码和生成的文档的路径。'within_subsection_order'使用了ExplicitOrder，并按照给定的顺序指定了示例的子节顺序。

现在，可以在examples文件夹中创建示例代码文件，并按照需要的顺序进行命名。示例代码文件的命名顺序将决定其在生成的文档中的展示顺序。请注意，示例代码文件必须以'.py'为扩展名，并位于'examples'文件夹中。

例如，假设在'examples'文件夹中有三个示例代码文件：'example_1.py'，'example_2.py'和'example_3.py'。根据上述配置文件中的指定顺序，在生成的文档中示例将按照'example_3'，'example_1'和'example_2'的顺序进行展示。

除了使用命名顺序外，还可以在示例代码文件中通过添加特定的Sphinx-Gallery标记来控制示例的排序。示例代码文件中的以下标记将覆盖在配置文件中指定的顺序：

# sphinx_gallery_sort_order = 2

上述代码中的数字2指示了示例的顺序，该顺序将覆盖配置文件中的顺序。可以根据需要为不同的示例指定不同的数字。

一旦配置文件和示例代码文件都设置好了，只需要运行以下命令即可生成文档并按照指定的顺序展示示例：

sphinx-build -b html . _build/html

上述命令将使用Sphinx-Gallery生成HTML格式的文档，并将生成的文档保存在'_build/html'文件夹中。在生成的文档中，示例将按照配置文件中指定的顺序进行展示。

最后，我们提供一个使用ExplicitOrder进行示例排序的具体例子。假设我们在'examples'文件夹中有三个示例代码文件：'plot_1.py'，'plot_2.py'和'plot_3.py'。我们希望在生成的文档中按照'plot_3'，'plot_1'和'plot_2'的顺序展示示例。为此，我们需要进行如下配置：

import sphinx_gallery.sorting

sphinx_gallery_conf = {
    'examples_dirs': 'examples',
    'gallery_dirs': 'gallery',
    'within_subsection_order': sphinx_gallery.sorting.ExplicitOrder([
        'plot_3',
        'plot_1',
        'plot_2',
    ])
}

配置文件设置好后，我们只需要运行以下命令即可生成文档：

sphinx-build -b html . _build/html

生成的文档将按照我们指定的顺序展示示例，从'plot_3'开始，然后是'plot_1'，最后是'plot_2'。这样，我们可以按照自己的需求对示例进行排序，并更好地控制示例的展示顺序。

总结起来，使用sphinx_gallery.sorting.ExplicitOrder()按照指定顺序排列示例非常简单。只需要在Sphinx的配置文件中进行一些额外的设置，然后在示例代码文件的命名或标记中指定顺序，就可以按照指定的顺序在生成的文档中展示示例。这对于构建易于理解和使用的文档非常有帮助。希望本文提供的例子能帮助你更好地使用Sphinx-Gallery中的ExplicitOrder排序机制。