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

sphinx_gallery.sorting.ExplicitOrder()是Sphinx的一个模块，可以用来对示例进行自定义排序。通过指定示例的顺序，我们可以控制示例在生成的文档中的展示顺序。

使用sphinx_gallery.sorting.ExplicitOrder()的第一步是定义一个排序列表，该列表包含了示例的文件名或者文件路径。然后，我们将该排序列表作为参数传递给ExplicitOrder()函数，该函数将返回一个用于排序的对象。我们可以在Sphinx配置文件中使用该对象，以按照自定义的顺序来生成示例。

下面是一个使用sphinx_gallery.sorting.ExplicitOrder()的例子：

首先，我们需要在Python脚本中导入sphinx_gallery.sorting.ExplicitOrder()模块：

from sphinx_gallery.sorting import ExplicitOrder

然后，我们可以定义一个排序列表，该列表包含了示例的文件名或者文件路径。示例按照出现顺序进行排序，越靠前的示例将在生成的文档中展示在越前面的位置。示例文件名或者文件路径应该是相对于示例目录的相对路径。

order = [
    'example1.py',
    'example2.py',
    'example3.py',
    ...
]

接下来，我们需要使用order列表来创建一个ExplicitOrder对象：

explicit_order = ExplicitOrder(order)

最后，我们可以在Sphinx配置文件中使用explicit_order对象来指定示例的排序规则：

sphinx_gallery_conf = {
    'examples_dirs': 'examples',
    'gallery_dirs': 'gallery',
    'image_scrapers': ('matplotlib',),
    'within_subsection_order': explicit_order,
}

在这个配置中，我们将'sphinx_gallery_conf'字典中的'within_subsection_order'键设置为explicit_order对象。这样，Sphinx将根据我们定义的顺序生成示例的展示顺序。

可以看到，sphinx_gallery.sorting.ExplicitOrder()提供了一种简单而有效的方法来自定义示例的排序规则。通过将示例按照自定义的顺序进行排序，我们可以更好地控制示例在生成文档中的展示位置，从而更好地展示我们的示例。