使用sphinx_gallery.sorting.ExplicitOrder()根据预定顺序对示例进行排序

sphinx_gallery.sorting.ExplicitOrder()是一个用于根据预定顺序对示例进行排序的函数，可以在Sphinx文档生成工具中使用。示例排序是指在生成文档过程中，对示例按照预定的顺序进行展示，而不是默认的按文件名排序。

为了使用sphinx_gallery.sorting.ExplicitOrder()函数，我们需要在Sphinx的配置文件中进行设置。首先，确保在配置文件中导入sphinx_gallery.sorting.ExplicitOrder()函数，例如：

from sphinx_gallery.sorting import ExplicitOrder

然后，我们可以创建一个新的示例排序器，如下所示：

example_sorter = ExplicitOrder([
    '../examples/example3.py',
    '../examples/example1.py',
    '../examples/example2.py'
])

在上述示例中，我们通过将示例的相对路径作为字符串传递给ExplicitOrder()函数来创建了一个新的示例排序器。在这个示例中，我们根据预定的顺序对"example3.py"，"example1.py"和"example2.py"进行排序。

接下来，我们将示例排序器应用于Sphinx的配置选项中。可以通过在配置文件中找到"extensions"选项，将示例排序器添加到"sphinx_gallery.sorting"模块中，例如：

extensions = [
    ...
    'sphinx_gallery.sorting',
]

然后，在配置文件中添加以下选项，以便将示例排序器应用于示例：

sphinx_gallery_conf = {
    ...
    'example_sorter': example_sorter,
}

通过将示例排序器设置为上述"sphinx_gallery_conf"字典的"example_sorter"键的值，我们可以确保示例根据预定的顺序进行排序。

最后，重新生成或编译Sphinx文档时，示例将按照我们在示例排序器中定义的顺序进行展示。这样，我们就可以根据需要对示例进行排序，而不是按默认的文件名排序。

总的来说，sphinx_gallery.sorting.ExplicitOrder()函数提供了一个简单而有效的方法，可以根据预定的顺序对示例进行排序。通过在Sphinx的配置文件中使用这个函数，我们可以灵活地控制示例的展示顺序，以更好地满足文档生成的需求。