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

Sphinx-Gallery是一个用于在Sphinx项目中自动生成示例文档和图库的工具。它可以通过在文档中的指定目录中查找并运行示例代码，然后将结果嵌入到生成的HTML文档中。Sphinx-Gallery还提供了对示例的排序功能，即使用sphinx_gallery.sorting.ExplicitOrder()类对示例进行排序。

sphinx_gallery.sorting.ExplicitOrder()类允许您根据特定的顺序对示例进行排序。这种排序可以按照示例的名称、文件名称、运行时间或任何其他您定义的顺序进行。使用ExplicitOrder()的基本步骤如下：

1. 在Sphinx项目的conf.py文件中导入需要的模块和类：

from sphinx_gallery.sorting import ExplicitOrder

2. 创建一个排序对象，并指定您想要的排序顺序。您可以通过将参数传递给ExplicitOrder()类的构造函数来指定排序顺序。参数可以是一个包含示例名称的列表，或是一个字典，其中示例名称作为键，对应的排序值作为值。示例名称可以是目录名称或文件名称。

order = ExplicitOrder(['example1', 'example2', 'example3'])

或者

order = ExplicitOrder({'example1': 0, 'example2': 1, 'example3': 2})

这里示例名称是通过目录/文件名称来表示。如果您希望根据其他条件进行排序（如示例的运行时间），则可以将示例名称替换为满足排序条件的其他标识符。

3. 将排序对象设置为Sphinx-Gallery的默认排序对象：

sphinx_gallery_conf = {
    # ...
    'sorting_order': order,
    # ...
}

通过将sorting_order键设置为排序对象，您可以将其应用于整个Sphinx-Gallery的文档生成过程。

现在，您的示例将按照您指定的排序顺序进行排序。请注意，如果有些示例没有包含在排序对象中，那么它们将按照默认的字母顺序放置。

下面是一个完整的示例，展示了如何使用sphinx_gallery.sorting.ExplicitOrder()对示例进行排序：

# conf.py

from sphinx_gallery.sorting import ExplicitOrder

# 创建排序对象
order = ExplicitOrder(['example1', 'example2', 'example3'])

# 将排序对象设置为默认排序对象
sphinx_gallery_conf = {
    'examples_dirs': 'examples',  # 示例目录
    'sorting_order': order,       # 使用排序对象进行排序
    # ...
}

在这个示例中，示例将按照'example1'、'example2'、'example3'的顺序进行排序。

通过使用sphinx_gallery.sorting.ExplicitOrder()类，您可以轻松地对示例进行排序，并更好地组织和呈现您的示例文档和图库。无论您是在编写教程文档、展示库功能还是演示项目示例，Sphinx-Gallery和ExplicitOrder()类都是极为有用的工具。