优化 Sphinx 文档树显示：移除模块全路径的实践指南

本文旨在解决使用 Sphinx 及其 autodoc 和 autosummary 扩展生成 Python 项目文档时，文档树或侧边栏中显示完整模块路径的问题。针对 pydata_sphinx_theme 等主题下 add_module_names = False 配置无效的情况，本文提供了一种通过修改 Jinja2 模板，利用 fullname.split(‘.’)[-1] 表达式来仅显示对象名而非完整路径的有效解决方案，从而显著提升文档的可读性和美观性。

引言

在使用 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 项目中，请遵循以下步骤：

1. 定位或创建自定义模板：
   • 首先，确保您的 conf.py 文件中 autosummary_generate 设置为 True，并且您已经配置了 autosummary 来使用自定义模板。
   • 自定义模板文件通常放置在 Sphinx 项目的 _templates 目录下（如果不存在，请创建）。
   • 例如，如果您希望自定义模块的显示，可以创建一个 _templates/custom-module-template.rst 文件。对于类、函数等，可能需要创建 custom-class-template.rst、custom-function-template.rst 等。