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

Sphinx-Gallery是一个强大的工具，可以从代码自动生成漂亮的示例文档。它可以自动读取python脚本文件中的示例代码，并将其转换为可执行的代码块，然后将其插入到文档中。

默认情况下，Sphinx-Gallery根据示例脚本文件在文件系统中的位置对示例进行排序。但是，有时我们可能想要对示例进行显式排序，以便以特定的顺序显示它们。这就是sphinx_gallery.sorting.ExplicitOrder()类的作用。

首先，我们需要两个示例脚本文件，以便测试显式排序的功能。我们将创建两个简单的脚本，分别命名为example1.py和example2.py。

example1.py的内容如下：

# example1.py

def greet(name):
    """
    This function takes a name as input and returns a greeting message.
    """
    return f"Hello, {name}!"

print(greet("Alice"))

example2.py的内容如下：

# example2.py

def multiply(a, b):
    """
    This function takes two numbers as input and returns their product.
    """
    return a * b

print(multiply(2, 3))

接下来，我们将创建一个名为index.rst的reStructuredText文件，用于编写文档。在这个文件中，我们将指定示例文件的显式排序顺序：

.. orembed:: python
    :start-after: # Import the modules
    :end-before: # Create the gallery

    from sphinx_gallery.sorting import ExplicitOrder

# 显式排序顺序
.. rst-class:: sphx-glr-generate-code

    示例文件的显式排序顺序是：example2.py，然后是example1.py。

.. rst-class:: sphx-glr-script-out

    我们按顺序运行这两个示例文件，你将看到以下输出结果：

.. highlight:: python
.. literalinclude:: example2.py

在这个例子中，我们使用orembbed指令来直接在reStructuredText文件中嵌入代码。首先，我们使用start-after参数来指定在导入模块之前的代码块。然后，我们使用end-before参数来指定在生成示例图库之前的代码块。

在这个示例中，我们导入了sphinx_gallery.sorting.ExplicitOrder类，并将其命名为order。

然后，我们使用ExplicitOrder类的实例order设置了示例脚本文件的显式排序顺序。在这个例子中，我们按照example2.py，然后是example1.py的顺序对它们进行排序。

最后，我们使用rst-class指令将显式排序顺序和示例代码插入到文档中。

运行Sphinx编译文档后，我们将看到示例按照我们指定的顺序显示在文档中。

示例文件的显式排序顺序是：example2.py，然后是example1.py。

我们按顺序运行这两个示例文件，你将看到以下输出结果：

python

def multiply(a, b):

"""

This function takes two numbers as input and returns their product.

"""

return a * b

print(multiply(2, 3))

`

你可以看到，在文档中，example2.py按照我们指定的顺序排在example1.py之前，并且它是第一个被显示的示例。

这就是使用sphinx_gallery.sorting.ExplicitOrder()对示例进行显式排序的方法。通过指定要显示示例的特定顺序，我们可以更好地控制文档中的示例显示。