Sphinx-Gallery库中FileNameSortKey()函数的使用注意事项和常见错误

Sphinx-Gallery是一个用于自动化生成代码示例文档的库。其中的FileNameSortKey()函数用于指定文件名的排序顺序。下面是关于FileNameSortKey()函数的使用注意事项、常见错误和使用示例：

1. 注意事项：

- FileNameSortKey()函数应作为sphinx_gallery.sorting模块的参数传递给Sphinx-Gallery的配置文件。

- FileNameSortKey()函数应该返回一个用于排序的关键字，而不是直接排序文件名本身。

2. 常见错误：

- 忘记导入FileNameSortKey()函数。在使用之前，应该从sphinx_gallery.sorting模块中导入该函数。

- 返回的关键字类型不是字符串或数字。FileNameSortKey()函数应返回字符串或数字类型的关键字，以便进行排序。

下面是一个使用FileNameSortKey()函数的示例：

from sphinx_gallery.sorting import FileNameSortKey

def gallery_sort_key(path):
    # 从文件路径中提取文件名
    file_name = path.name

    # 从文件名中提取排序关键字
    split_name = file_name.split('_')
    num = int(split_name[0]) if split_name[0].isdigit() else float(split_name[0])
    key = (num, file_name)

    return key

sphinx_gallery_conf = {
    ...
    'examples_dirs': 'examples',
    'gallery_dirs': 'examples/gallery',
    'within_subsection_order': FileNameSortKey,
    ...
}

在上面的示例中，我们定义了一个名为gallery_sort_key()的函数，该函数从文件路径中提取文件名，并根据文件名中的排序关键字进行排序。将FileNameSortKey作为within_subsection_order配置参数的值，确保Sphinx-Gallery按照现定义的排序规则对文件进行排序。

请注意，示例中的排序规则是将文件名分割成两部分： 部分是一个数字（整数或浮点数），第二部分是原始文件名。这样，文件将按照数字和文件名的组合进行排序。例如，文件名为1_example.py的文件将先于2_example.py文件，但它们都会排在10_example.py文件之前。

通过理解FileNameSortKey()函数的使用注意事项和常见错误，我们可以更好地使用Sphinx-Gallery库来自动生成代码示例文档，并按照所需的顺序对文件进行排序。