引言
在使用 Sphinx 为 Python 项目生成自动化文档时，autodoc 和 autosummary 是两个强大的扩展，它们能够自动从代码中提取文档字符串并生成对应的 reStructuredText (RST) 文件。然而，一个常见的痛点是，生成的文档树（通常显示在侧边栏）或自动生成的摘要列表中，Python 对象（如函数、类、模块）的名称会以其完整的合格路径形式出现，例如 my_package.my_python_module1.function_A。对于大型项目而言，这种冗长的显示方式会降低文档的清晰度和可读性，使得导航变得困难。
尽管 Sphinx 提供了一个 add_module_names = False 的配置选项，旨在移除模块名称前缀，但实践证明，对于某些主题（如 pydata_sphinx_theme 或 sphinx_book_theme），这个选项并不能完全解决 autosummary 在文档树中显示完整路径的问题。本文将深入探讨此问题，并提供一个基于 Jinja2 模板修改的通用解决方案，以实现简洁的文档树显示。
问题剖析：冗余的文档树路径
为了更好地理解问题，我们以一个典型的 Python 项目结构为例：
代码结构: ├───my_package │ └───my_python_module1 (包含 function_A) │ └───my_directory │ └───my_python_module2 (包含 function_B)
当使用 autodoc 和 autosummary 默认配置生成文档时，您可能会看到如下的文档树结构：
生成的文档树: ├───my_package │ └───my_package.my_python_module1 │ └───my_package.my_python_module1.function_A │ └───my_package.my_directory │ └───my_package.my_directory.my_python_module2 │ └───my_package.my_directory.my_python_module2.function_B
我们期望的文档树结构则更为简洁：
期望的文档树: ├───my_package │ └───my_python_module1 │ └───function_A │ └───my_directory │ └───my_python_module2 │ └───function_B
显然，期望的结构去除了冗余的包名和模块路径，只保留了对象本身的名称，大大提升了可读性。add_module_names = False 选项主要影响的是由 autodoc 生成的 RST 文件中标题的显示，而不是 autosummary 在生成摘要列表或侧边栏导航时所使用的名称。因此，我们需要更深层次地介入 autosummary 的渲染机制。
解决方案：定制 Jinja2 模板
autosummary 扩展在生成摘要列表时，会利用 Jinja2 模板来渲染每个条目。默认情况下，它使用 fullname 变量，该变量包含了对象的完整合格路径。解决之道在于修改这些模板，截取 fullname 的最后一部分，即对象本身的名称。
假设您正在使用一个名为 custom-module-template.rst 的自定义模板（或任何其他由 autosummary 的 :template: 选项指定的模板），其核心修改点在于模板顶部的标题渲染部分。
原模板片段（位于 custom-module-template.rst 或类似文件中）：
{{ fullname | escape | underline}}
.. automodule:: {{ fullname }}这里的 {{ fullname }} 直接输出了对象的完整路径。
修改后的模板片段：
{{ fullname.split('.')[-1] | escape | underline}}
.. automodule:: {{ fullname }}核心修改解析：
- fullname: 这是 Jinja2 模板中由 autosummary 提供的变量，它包含了当前对象的完整合格名称（例如 my_package.my_python_module1.function_A）。
- .split('.'): 这是一个 Python 字符串方法，在 Jinja2 模板中可以直接使用。它将 fullname 字符串按照点号 . 进行分割，返回一个字符串列表。例如，"my_package.my_python_module1.function_A".split('.') 将得到 ['my_package', 'my_python_module1', 'function_A']。
- [-1]: 这是 Python 列表的索引操作，用于获取列表中的最后一个元素。在上述例子中，[-1] 将得到 'function_A'。
- | escape: 这是一个 Jinja2 过滤器，用于对输出的字符串进行 HTML 转义，防止潜在的安全问题或渲染错误。
- | underline: 这是一个 Sphinx/Jinja2 过滤器，用于在 reStructuredText 中为文本添加下划线，通常用于生成标题。
通过这一简单的修改，模板在渲染标题时将不再显示完整的路径，而只会显示对象的简单名称。
实施步骤
要将此解决方案应用到您的 Sphinx 项目中，请遵循以下步骤：
-
定位或创建自定义模板：
- 首先，确保您的 conf.py 文件中 autosummary_generate 设置为 True，并且您已经配置了 autosummary 来使用自定义模板。
- 自定义模板文件通常放置在 Sphinx 项目的 _templates 目录下（如果不存在，请创建）。
- 例如，如果您希望自定义模块的显示，可以创建一个 _templates/custom-module-template.rst 文件。对于类、函数等，可能需要创建 custom-class-template.rst、custom-function-template.rst 等。
