使用sphinx_gallery.sorting.ExplicitOrder()实现示例的明确排序

Sphinx-Gallery是一个用于构建示例画廊的工具，它可以自动从文档字符串中提取示例代码，并根据需要执行这些代码，并将其结果插入到文档中。它为开发人员提供了一种将示例代码与文档保持同步的简单方法。

在默认情况下，Sphinx-Gallery会按照文件创建的顺序对示例进行排序，并将其按照字母顺序显示在画廊中。然而，有时候我们希望对示例进行自定义排序，这就需要使用sphinx_gallery.sorting.ExplicitOrder()类来实现了。

首先，在Sphinx项目的conf.py文件中导入sphinx_gallery.sorting.ExplictOrder类：

from sphinx_gallery.sorting import ExplicitOrder

然后，可以在conf.py文件中使用ExplicitOrder()类来定义示例的显示顺序：

sphinx_gallery_conf = {
    'examples_dirs': 'examples',   # 示例代码所在的目录
    'gallery_dirs': 'gallery',     # 生成的示例画廊的目录
    'within_subsection_order': ExplicitOrder(['example1.py', 'example2.py', 'example3.py'])
}

在上面的示例中，'within_subsection_order'参数指定了示例文件的明确顺序。它接受一个列表作为参数，其中列表的顺序决定了示例的显示顺序。在这个示例中，我们明确指定了example1.py、example2.py和example3.py的顺序。

之后，当使用sphinx-build命令构建文档时，Sphinx-Gallery将按照我们定义的顺序对示例进行排序，并在生成的文档中按照这个顺序显示这些示例。

除了在conf.py文件中明确指定示例的顺序外，我们还可以在示例文件自身的文档字符串中使用特殊的标记来为示例指定顺序。例如，在示例文件的文档字符串的开头添加以下标记：

# sphinx_gallery_sort_order = 2

在这个示例中，我们将示例的顺序设置为2。Sphinx-Gallery将按照这个顺序对示例进行排序，并将其显示在画廊中。

需要注意的是，当示例同时在conf.py文件和示例文件中指定顺序时，以示例文件中的顺序为准。

总结来说，使用sphinx_gallery.sorting.ExplicitOrder类可以帮助我们在Sphinx-Gallery中实现示例的自定义排序。我们可以在conf.py文件中明确指定示例的顺序，或者在示例文件中使用特殊的标记来指定顺序。这样，我们就能够更好地控制示例在画廊中的显示顺序，使我们的文档更加清晰和有条理。