使用sphinx_gallery.sorting.ExplicitOrder()对示例进行显示排序

Sphinx-Gallery是一个用于创建和显示示例代码的工具。它可以根据Sphinx文档的配置自动运行示例代码，并将其结果嵌入到生成的文档中。示例代码是以目录为单位进行组织，按照默认的排序规则进行显示。

但有时候，我们可能希望手动指定示例代码的显示顺序，而不使用默认的排序规则。这时就可以使用Sphinx-Gallery库中的ExplicitOrder()类来实现。

使用Sphinx-Gallery进行示例代码显示排序分为两个步骤：创建排序文件和配置Sphinx文档。

步骤一：创建排序文件

创建一个名为examples_order.txt的文本文件，并将示例代码的文件名按照你想要的顺序写入该文件中。每行一个文件名。

例如，假设我们有三个示例代码文件：example1.py，example2.py和example3.py。我们希望先显示example3.py，然后是example1.py，最后是example2.py。我们可以在examples_order.txt中写入下面的内容：

example3.py
example1.py
example2.py

注意，文件名不需要包含完整路径，只需写入示例代码文件的文件名即可。

步骤二：配置Sphinx文档

打开你的Sphinx文档的conf.py文件，并添加以下代码：

from sphinx_gallery.sorting import ExplicitOrder

sphinx_gallery_conf = {
    # 其他配置项...
    'examples_dirs': 'path/to/examples',
    'gallery_dirs': 'path/to/gallery',
    'filename_pattern': '/^example[0-9]*\\.py$',
    'binder': {'org': 'myorg', 'repo': 'myrepo', 'branch': 'master', 'binderhub_api_token': 'mytoken'}, # 可选项，用于绑定Jupyter notebook
    'sorting': ExplicitOrder('examples_order.txt'), # 显示排序使用ExplicitOrder类
    # 其他配置项...
}

在以上代码中，需要修改examples_dirs和gallery_dirs分别为示例代码的目录和生成的示例代码文档的目录。filename_pattern用于匹配示例代码文件的文件名模式，确保其与实际的文件名模式匹配。

注意，sorting选项需要使用ExplicitOrder类的实例，并将排序文件的路径作为参数传入。

保存并关闭conf.py文件后，在命令行中执行sphinx-build命令重新生成文档，示例代码将按照在排序文件中指定的顺序进行显示。

综上所述，通过使用Sphinx-Gallery库中的ExplicitOrder()类，我们可以轻松地对示例代码进行显示排序。这在需要特定的示例展示顺序时非常有用，特别是当示例之间存在逻辑依赖关系或有显示顺序的要求时。