使用sphinx_gallery.sorting.ExplicitOrder()对示例进行指定排列

sphinx_gallery是一个让用户可以在文档中方便地展示和运行代码示例的工具。使用sphinx_gallery.sorting.ExplicitOrder()可以对示例进行指定排列，即按照用户定义的顺序来展示示例。

在默认情况下，sphinx_gallery会按照示例文件的名称进行排序，但如果用户希望按照自己的方式来排列示例，就可以使用ExplicitOrder()。

首先，让我们了解一下如何使用sphinx_gallery展示示例。假设我们有一个名为"example.py"的示例文件，其中有一个名为"example_function"的函数需要展示。我们可以在sphinx的文档注释中使用"sphinx_gallery"标记来指定要展示的示例代码和相关说明，如下所示：

"""
This is a documentation example.

.. sphinx_gallery::                          # sphinx_gallery标记
    :filename: example.py                     # 示例文件名
    :function: example_function                # 要展示的函数名
    :linenos:                                 # 是否展示行号
    :caption: Example Caption                  # 示例的标题
    :plot_directive: plot                      # 使用的绘图指令

More documentation here...
"""

当我们运行sphinx-build命令来生成文档时，sphinx_gallery会自动从示例文件中提取example_function的代码，并在文档中创建一个相应的示例模块。这样用户就可以在生成的文档中看到示例代码，并可以直接运行它们。

然而，默认排序规则是按照示例文件的名称来排序的，这可能并不是我们希望的方式。我们希望能够按照我们自己的顺序来展示示例，比如按照示例的重要性、复杂度或逻辑顺序来排列。

这时，就可以使用sphinx_gallery.sorting.ExplicitOrder()来指定排序顺序。具体步骤如下：

1. 在sphinx的配置文件（通常是conf.py）中导入需要的模块：

from sphinx_gallery.sorting import ExplicitOrder

2. 在配置文件中创建一个列表，其中包含示例文件的名称，并按照指定顺序排列。示例文件的名称可以是不带扩展名的路径。

examples = [
    'example1',
    'example3',
    'example2',
]

3. 在配置文件中设置example_sorter为ExplicitOrder()的一个实例，并将列表传递给它。这告诉sphinx_gallery使用我们指定的顺序来排列示例。

example_sorter = ExplicitOrder(examples)

4. 将example_sorter设置为sphinx_gallery_conf的'examples_dirs'选项的值。

sphinx_gallery_conf = {
    ...
    'examples_dirs': 'path/to/examples',
    'gallery_dirs': 'path/to/gallery',
    'example_sorter': example_sorter,
    ...
}

这样，在生成文档时，sphinx_gallery将按照我们在列表中指定的顺序展示示例。首先展示的将是example1，然后是example3，最后是example2。

总结起来，使用sphinx_gallery.sorting.ExplicitOrder()对示例进行指定排列的步骤如下：

1. 导入sphinx_gallery.sorting.ExplicitOrder。

2. 创建一个列表，按照所需顺序包含示例文件的名称。

3. 创建ExplicitOrder()的一个实例，并将列表传递给它。

4. 将example_sorter设置为sphinx_gallery_conf的'example_sorter'选项的值。