优化Sphinx文档树显示：在autosummary中移除模块全路径

本教程旨在解决Sphinx文档生成中，autodoc和autosummary扩展在侧边栏或目录树中显示完整模块路径的问题。针对pydata_sphinx_theme等主题下add_module_names = False无效的情况，文章详细介绍了如何通过修改autosummary的Jinja2模板，利用fullname.split(‘.’)[-1]技巧，仅显示函数或模块的短名称，从而优化文档的视觉整洁度和可读性。

1. 问题描述：冗余的模块全路径

在使用sphinx结合autodoc和autosummary扩展自动生成python项目文档时，尤其是在使用如pydata_sphinx_theme或sphinx_book_theme等现代主题时，一个常见的问题是文档的侧边栏（toc）或生成的摘要页面中，python对象（如模块、函数、类）会显示其完整的导入路径。例如，my_package.my_python_module1.function_a，而非简洁的function_a。

尽管Sphinx提供了conf.py中的add_module_names = False配置项，旨在移除对象前的模块名称，但在某些主题下，此设置可能无法完全生效，导致文档树依然显示冗长的全路径，影响整体的视觉整洁度和用户体验。

以下是一个典型的代码结构及其默认生成的文档树与期望的文档树对比：

代码结构示例:

├───my_package │   └───my_python_module1 (包含 function_A) │   └───my_directory │       └───my_python_module2 (包含 function_B)

默认生成的文档树示例:

├───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

2. 解决方案：定制autosummary模板

autosummary扩展在生成摘要和链接时，内部使用Jinja2模板来渲染内容。默认情况下，这些模板会使用fullname变量，该变量包含了对象的完整路径。要解决上述问题，我们需要定制这些模板，将fullname替换为只包含对象短名称的部分。

核心思路是利用Python字符串的split(‘.’)[-1]方法来提取全路径的最后一部分，即对象本身的名称。

2.1 修改模板文件

假设你有一个自定义的autosummary模板文件，例如custom-module-template.rst，或者你需要创建一个新的模板文件。

原模板片段 (通常在文件顶部):

{{ fullname | escape | underline}}

修改后的模板片段:

将上述行替换为：

{{ fullname.split('.')[-1] | escape | underline}}

完整示例（以custom-module-template.rst为例）:

{{ fullname.split('.')[-1] | escape | underline}}  .. automodule:: {{ fullname }}     {% block attributes %}    {% if attributes %}    .. rubric:: Module attributes     .. autosummary::       :toctree:    {% for item in attributes %}       {{ item }}    {%- endfor %}    {% endif %}    {% endblock %}     {% block functions %}    {% if functions %}    .. rubric:: {{ _('Functions') }}     .. autosummary::       :toctree:       :nosignatures:    {% for item in functions %}       {{ item }}    {%- endfor %}    {% endif %}    {% endblock %}     {% block classes %}    {% if classes %}    .. rubric:: {{ _('Classes') }}     .. autosummary::       :toctree:       :template: custom-class-template.rst  {# 注意：这里可能需要另一个定制的类模板 #}       :nosignatures:    {% for item in classes %}       {{ item }}    {%- endfor %}    {% endif %}    {% endblock %}     {% block exceptions %}    {% if exceptions %}    .. rubric:: {{ _('Exceptions') }}     .. autosummary::       :toctree:    {% for item in exceptions %}       {{ item }}    {%- endfor %}    {% endif %}    {% endblock %}  {% block modules %} {% if modules %} .. autosummary::    :toctree:    :template: custom-module-template.rst {# 确保这里引用的是当前修改的模板 #}    :recursive: {% for item in modules %}    {{ item }} {%- endfor %} {% endif %} {% endblock %}

说明:

• fullname.split(‘.’)[-1]：这行代码是关键。它将完整的对象路径（如my_package.my_module.my_function）按点.分割成列表，然后取列表的最后一个元素，即my_function。
• escape：确保输出的字符串中的特殊字符被正确转义，防止RST解析错误。
• underline：为标题添加下划线，这是Sphinx RST语法中标题的常见格式。

2.2 配置conf.py

为了让Sphinx使用你的自定义模板，你需要在conf.py文件中进行相应的配置。

1. 创建模板目录: 在Sphinx项目的source（或你指定的源目录）下创建一个名为_templates的目录（如果它不存在）。然后，在该目录下创建一个autosummary子目录。将你的自定义模板文件（例如custom-module-template.rst）放入_templates/autosummary/目录中。

2. 在conf.py中指定模板路径:

   # conf.py  # ... 其他配置 ...  # 指定autosummary模板目录 autosummary_generate = True # 确保autosummary自动生成 autosummary_template_dir = '_templates/autosummary'  # 设置默认的autosummary模板（如果需要） # 如果你的autosummary指令没有显式指定:template:，则会使用这些默认模板 # 你可以根据需要创建 module.rst, class.rst, function.rst 等 # 例如，如果你希望所有模块都使用 custom-module-template.rst # 你可以将其重命名为 module.rst 并放在 _templates/autosummary/ # 或者在你的.rst文件中显式引用:template: custom-module-template.rst

3. 在你的.rst文件中引用自定义模板: 如果你的autosummary指令需要使用这个自定义模板，请确保在指令中添加:template:选项：

   .. autosummary::    :toctree:    :template: custom-module-template.rst    :recursive:     my_package

   或者，如果你将修改后的模板重命名为module.rst（或class.rst, function.rst等），并放置在_templates/autosummary/目录下，那么autosummary在生成对应类型的文档时，会默认查找并使用这些模板，无需在指令中显式指定:template:。

3. 注意事项

• 作用范围: 这个修改主要影响由autosummary生成的.rst文件中的标题和目录树中的显示名称。它不会改变Python对象在代码中的实际全限定名，也不会影响autodoc在文档内容中引用对象时的全路径显示（除非你对autodoc也进行了更深层次的定制）。
• 模板粒度: autosummary可以为不同类型的对象（模块、类、函数、属性、异常）使用不同的模板。你可能需要根据需要修改module.rst、class.rst、function.rst等多个模板文件，以确保所有类型的对象都能显示短名称。本教程的示例主要针对模块和函数。
• 主题兼容性: 这种模板修改方法是基于Jinja2模板引擎的通用技巧，理论上与Sphinx主题无关。然而，某些主题可能会有其特定的侧边栏渲染逻辑，但在大多数情况下，修改autosummary生成的.rst文件标题会直接影响侧边栏的显示。
• 可读性权衡: 移除全路径可以使文档树更简洁，但在某些情况下，如果模块名或函数名不够独特，仅显示短名称可能会导致歧义。在大型项目中，适当保留部分路径（例如只移除包名，保留模块名）可能更合适，但这需要更复杂的模板逻辑。

4. 总结

通过定制autosummary的Jinja2模板，并利用fullname.split(‘.’)[-1]技巧，我们可以有效地控制Sphinx文档中对象名称的显示方式，移除冗余的模块全路径，从而使生成的文档树更加简洁、易读。这种方法提供了比add_module_names = False更精细的控制，尤其适用于那些对该配置项不敏感的Sphinx主题。掌握模板定制是高级Sphinx用户提升文档质量的关键技能之一。