使用sphinx_gallery.sorting.ExplicitOrder()对示例按照预定顺序进行排列

sphinx_gallery.sorting.ExplicitOrder()是一个用于对Sphinx示例进行排序的类。它允许用户根据自己的需求，将示例按照特定的顺序进行排列。

在使用ExplicitOrder()之前，我们需要先安装sphinx_gallery包。可以使用以下命令来安装：

pip install sphinx_gallery

接下来，在Sphinx的配置文件（通常是conf.py）中，需要添加以下代码：

from sphinx_gallery.sorting import ExplicitOrder

# 示例排序
sphinx_gallery_conf = {
    # ...
    'examples_dirs': "../examples",  # 示例文件夹的路径
    'gallery_dirs': "auto_examples",  # 生成示例的目标文件夹路径
    'within_subsection_order': ExplicitOrder([
        '../examples/example3.py',
        '../examples/example1.py',
        '../examples/example2.py'
    ]),
    # ...
}

在上面的示例中，我们列出了三个示例的文件路径，并将它们传递给了ExplicitOrder()类的构造函数。这意味着我们希望这三个示例按照指定的顺序进行排列。

更具体地说，'within_subsection_order'参数是一个字典，指定了每个小节下示例文件的预定顺序。在这个例子中，我们假设有一个小节，包含了这三个示例的文件。'../examples/example3.py'将显示在前面，其次是'../examples/example1.py'，最后是'../examples/example2.py'。

在排序配置中，您还可以使用通配符（*）来匹配多个文件。这是一个非常有用的功能，特别是当您的示例文件非常多时。

当使用指定顺序排列示例后，可以使用以下命令生成Sphinx文档：

sphinx-build -b html sourcedir builddir

其中，'sourcedir'是Sphinx项目的源代码目录，而'builddir'是生成的文档目录。

当文档生成完毕后，示例文件将按照预定顺序在文档中进行展示。

总结一下，使用sphinx_gallery.sorting.ExplicitOrder()可以很方便地对Sphinx示例进行排序。通过在配置文件中指定示例文件的预定顺序，可以控制示例的展示顺序，并使文档更加清晰易读。