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

Sphinx-Gallery是一个用于自动生成代码示例的工具，可以帮助开发者快速创建、展示和文档化可运行的示例代码。默认情况下，Sphinx-Gallery根据示例文件的名称对示例进行排序。然而，当示例的数量增加时，可能需要使用自定义规则对示例进行排序。

为了实现自定义排序，Sphinx-Gallery提供了一个名为ExplicitOrder()的类。通过使用此类，可以根据自己的规则对示例进行排序。

首先，我们需要在Sphinx的配置文件（通常是conf.py）中添加一些代码来指定自定义排序规则。这可以通过添加以下代码片段来完成：

from sphinx_gallery.sorting import ExplicitOrder

sphinx_gallery_conf = {
    # ...其他配置
    'sort_gallery_examples': ExplicitOrder(),  # 使用自定义排序规则
}

接下来，我们需要创建一个文本文件，其中列出了示例文件的名称以及其想要的顺序。名为example_order.txt的文件可以如下所示：

example1.py
example3.py
example2.py

在这个例子中，我们希望示例1（example1.py）在示例3（example3.py）之前，示例2（example2.py）在示例3（example3.py）之后。

接下来，将该文件添加到项目的某个目录中，并在Sphinx-Gallery的配置文件中设置examples_dirs选项为包含示例文件的目录。例如：

sphinx_gallery_conf = {
    'examples_dirs': 'examples',
    # ...其他配置
}

最后，重新生成Sphinx文档，并观察示例的排序。

此时，示例将按照example_order.txt文件中定义的顺序进行排序。

需要注意的是，仅提供在example_order.txt文件中列出的示例文件将被包含在文档中。如果有其他示例文件存在于示例目录中，但在该文件中未指定顺序，则不会包含在文档中。

这就是使用Sphinx-Gallery中的ExplicitOrder()对示例进行自定义排序的步骤。通过定义一个文本文件来指定示例的顺序，开发者可以按照自己的需求进行排序，以展示最合适的示例。这对于展示示例的逻辑顺序或者按主题或难度级别对示例进行分组非常有用。