使用sphinx_gallery.sorting.ExplicitOrder()按照自定义顺序对示例进行排序

在Sphinx中，具有sphinx_gallery拓展的功能可以将Python示例代码自动提取并展示在生成的文档中。然而，默认情况下，这些示例代码是根据其文件名的字母顺序排序的。如果我们想要按照我们自定义的顺序对这些示例进行排序，我们可以使用sphinx_gallery.sorting.ExplicitOrder()。

sphinx_gallery.sorting.ExplicitOrder() 是sphinx_gallery.sorting模块中提供的一个类，它允许我们指定示例代码的顺序。具体来说，我们可以通过示例代码文件的路径或名称来定义顺序，并根据自定义排序规则对示例进行排序。

下面是使用sphinx_gallery.sorting.ExplicitOrder()对示例进行排序的步骤：

1. 首先，我们需要在Sphinx配置文件（conf.py）中导入sphinx_gallery.sorting.ExplicitOrder()：

from sphinx_gallery.sorting import ExplicitOrder

2. 然后，我们可以在配置文件中定义示例代码的顺序。可以使用示例代码文件的相对路径或名称以及它们在所需顺序中的位置来定义示例的排序。例如，假设我们有三个示例代码文件：example1.py，example2.py和example3.py。我们想要按照example2.py，example1.py和example3.py的顺序对这些示例进行排序。我们可以在配置文件中添加如下代码：

sphinx_gallery_conf = {
    ...
    'examples_dirs': 'path/to/examples',
    'gallery_dirs': 'path/to/gallery',
    'within_subsection_order': ExplicitOrder(
        ['example2.py', 'example1.py', 'example3.py'])
    ...
}

3. 最后，重新运行Sphinx生成文档。现在，示例将按照我们自定义的顺序显示在生成的文档中。

下面是一个完整的示例，展示了如何使用sphinx_gallery.sorting.ExplicitOrder()对示例进行排序：

1. 假设我们有以下三个示例代码文件，分别存储在examples文件夹下：example1.py，example2.py和example3.py。

2. 在Sphinx配置文件（conf.py）中导入sphinx_gallery.sorting.ExplicitOrder()：

from sphinx_gallery.sorting import ExplicitOrder

3. 在配置文件中添加如下配置：

sphinx_gallery_conf = {
    'examples_dirs': 'examples',
    'gallery_dirs': 'gallery',
    'within_subsection_order': ExplicitOrder(
        ['example2.py', 'example1.py', 'example3.py'])
}

4. 重新运行Sphinx生成文档。

此时，生成的文档中的示例将按照example2.py，example1.py和example3.py的顺序显示。

通过使用sphinx_gallery.sorting.ExplicitOrder()，我们可以自定义示例代码的顺序，以便更好地组织和展示在生成的文档中。无论您是想按照某个特定的逻辑来排序示例，或者只是想将某些重要的示例放在前面，sphinx_gallery.sorting.ExplicitOrder()都能够满足您的需求。