在使用Sphinx结合autodoc和autosummary扩展自动生成Python项目文档时，一个常见的问题是，在文档的侧边栏（或目录树，ToC）中，模块、函数或类的名称会默认显示其完整的Python导入路径，例如 my_package.my_python_module1.function_A。这对于大型项目而言，会导致侧边栏显得冗长且难以阅读，降低了导航效率。
以下是一个典型的项目结构及其默认生成的文档树示例：
项目代码结构：
├───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
尽管Sphinx提供了 add_module_names = False 配置项，但它主要影响文档页面内部的引用显示，对于 pydata_sphinx_theme 或 sphinx_book_theme 等主题所生成的侧边栏导航树，该设置通常无效。因此，我们需要一种更直接的方式来控制 autosummary 生成的条目名称。
解决此问题的核心在于定制 autosummary 扩展所使用的Jinja2模板。autosummary 在生成每个模块、类或函数的文档页面时，会使用一个模板来渲染其内容，包括页面标题和内部结构。通过修改模板中用于显示名称的部分，我们可以实现路径精简。
关键的修改点在于利用Jinja2模板引擎的字符串处理能力，将完整的模块路径 (fullname) 分割并只取其最后一部分。
在你的Sphinx项目 source 目录下（或你配置的 templates_path 目录下），创建一个名为 _templates/autosummary/custom-module-template.rst 的文件。如果已经有类似的自定义模板，直接修改即可。
将以下内容复制到 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] | escape | underline}}
通过这一行代码，无论 fullname 是模块、函数还是类的完整路径，其在侧边栏和页面标题中显示的都将是其最终的短名称。
确保你的 conf.py 文件中正确配置了 templates_path，指向包含你自定义模板的目录。例如：
# conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('.')) # 确保你的项目路径被Sphinx识别
# ... 其他配置 ...
templates_path = ['_templates'] # 指向你的自定义模板目录在你的主 rst 文件（例如 index.rst 或 modules.rst）中，当你使用 autosummary 指令来生成模块列表时，确保通过 :template: 选项引用你创建的自定义模板：
.. toctree:: :maxdepth: 2 :caption: Contents: .. autosummary:: :toctree: _autosummary :template: custom-module-template.rst :recursive: my_package
这里的 :toctree: _autosummary 会在 _autosummary 目录下生成对应的 rst 文件，而 :template: custom-module-template.rst 则确保这些生成的 rst 文件内容（包括它们的标题，进而影响侧边栏显示）会使用你定制的模板。:recursive: 选项则允许 autosummary 递归地发现并文档化子模块。
通过简单地修改 autosummary 的Jinja2模板，利用 fullname.split('.')[-1] 表达式，我们可以有效地将Sphinx文档侧边栏中冗余的模块全路径精简为简洁的短名称。这不仅显著提升了文档的视觉整洁度，也极大改善了用户在大型项目文档中的导航体验，使其更加直观和高效。这种方法提供了一个强大且灵活的途径来定制Sphinx的输出，以满足特定的项目需求和审美偏好。
以上就是优化Sphinx文档树显示：精简侧边栏模块路径的详细内容，更多请关注php中文网其它相关文章！
每个人都需要一台速度更快、更稳定的 PC。随着时间的推移，垃圾文件、旧注册表数据和不必要的后台进程会占用资源并降低性能。幸运的是，许多工具可以让 Windows 保持平稳运行。
Copyright 2014-2025 //m.sbmmt.com/ All Rights Reserved | php.cn | 湘ICP备2023035733号
698
收藏
