使用sphinx_gallery.sorting.ExplicitOrder()按照指定次序对示例进行排序

Sphinx-Gallery是Sphinx的一个插件，用于在Sphinx生成的文档中自动展示和运行Python示例代码。它能够自动获取源代码，并将其转换成可运行的示例，并将结果插入到文档中。

Sphinx-Gallery提供了一些配置选项，以帮助我们对生成的示例进行排序。其中一个常用的排序选项是sorting，它允许我们按照不同的方法对示例进行排序。在本文中，我们将使用这个选项中的ExplicitOrder()方法来按照指定的顺序对示例进行排序。

ExplicitOrder()方法接受一个字典作为参数，字典的键是示例文件的路径，值是示例的排序优先级。示例文件的路径可以是相对于conf.py文件所在目录的相对路径，也可以是绝对路径。

下面是一个使用ExplicitOrder()方法对示例进行排序的示例。我们假设我们有以下三个示例文件：example1.py，example2.py和example3.py。

首先，在我们的Sphinx项目的conf.py中，我们需要导入ExplicitOrder类，并将其作为sphinx_gallery.sorting的别名：

from sphinx_gallery.sorting import ExplicitOrder as Order

然后，我们可以在sphinx_gallery_conf.py中，通过指定示例文件的排序优先级，来对示例进行排序。

sphinx_gallery_conf = {
    'examples_dirs': 'path/to/examples',
    'gallery_dirs': 'path/to/gallery',
    'sorting': Order({
        'example1.py': 3,
        'example2.py': 1,
        'example3.py': 2,
    }),
}

在上面的例子中，我们通过将示例文件和它们的排序优先级作为键值对添加到Order()的实例中，来指定示例的排序顺序。

运行Sphinx生成文档后，生成的示例将按照我们指定的顺序排列。在本例中，example2.py将显示在最前面，接下来是example3.py，最后是example1.py。

总结：使用ExplicitOrder()方法可以轻松地按照指定的顺序对Sphinx-Gallery生成的示例进行排序。我们只需要在sphinx_gallery_conf.py中指定示例文件的排序优先级即可。这种排序方法对于需要按照特定顺序展示示例的项目非常有用。