Sphinx 文档生成：去除侧边栏模块树中的完整路径-Python教程-PHP中文网

Sphinx 文档生成：去除侧边栏模块树中的完整路径

花韻仙語

发布： 2025-08-15 21:02:15

原创

768人浏览过

sphinx 文档生成：去除侧边栏模块树中的完整路径

本文档旨在解决在使用 Sphinx 生成文档时，侧边栏模块树显示完整模块路径的问题。通过修改自定义 Jinja2 模板，可以只显示模块或函数的名称，从而使文档结构更加清晰简洁，提高用户体验。该方法适用于多种 Sphinx 主题，例如 pydata_sphinx_theme 和 sphinx_book_theme。

在使用 Sphinx 生成文档时，特别是使用 autodoc 和 autosummary 扩展自动生成 API 文档时，侧边栏显示的模块树默认会包含完整的模块路径，例如 my_package.my_module.my_function。这种冗长的路径在大型项目中会显得非常累赘，影响文档的可读性。我们希望只显示 my_function，从而简化侧边栏的结构。

要实现这个目标，我们需要修改 Sphinx 使用的 Jinja2 模板。具体步骤如下：

找到或创建自定义模块模板。 通常，你需要创建一个自定义的模块模板，例如 custom-module-template.rst，并将其配置到 autosummary 指令中。如果你已经有一个自定义模板，可以直接修改它。
修改模板中的标题部分。 在模板中，找到生成标题的部分，通常是类似 {{ fullname | escape | underline}} 的代码。这里的 fullname 变量包含了模块或函数的完整路径。
使用字符串分割提取名称。 使用 Jinja2 的字符串处理功能，将 fullname 按照 . 分割，并提取最后一个元素，即模块或函数的名称。可以使用如下代码：
```
{{ fullname.split('.')[-1] | escape | underline}}
```
登录后复制
这行代码的含义是：
- fullname.split('.'): 将 fullname 按照 . 分割成一个列表。
- [-1]: 取列表的最后一个元素，即模块或函数的名称。
- escape: 对名称进行转义，防止出现 HTML 注入等安全问题。
- underline: 为标题添加下划线。
保存修改后的模板。 保存修改后的 custom-module-template.rst 文件。

影像之匠PixPretty
商业级AI人像后期软件，专注于人像精修，色彩调节及批量图片编辑，支持Windows、Mac多平台使用。适用于写真、婚纱、旅拍、外景等批量修图场景。

299

查看详情
重新生成 Sphinx 文档。 运行 sphinx-build 命令重新生成文档。

示例：

假设你的 custom-module-template.rst 文件内容如下：

{{ fullname | escape | underline}}

.. automodule:: {{ fullname }}

   {% block functions %}
   {% if functions %}
   .. rubric:: Functions

   .. autosummary::
      :toctree:
      :nosignatures:
   {% for item in functions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

登录后复制

将其修改为：

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

.. automodule:: {{ fullname }}

   {% block functions %}
   {% if functions %}
   .. rubric:: Functions

   .. autosummary::
      :toctree:
      :nosignatures:
   {% for item in functions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

登录后复制

注意事项：

确保你的 Sphinx 项目正确配置了 autodoc 和 autosummary 扩展。
确认你使用的 Sphinx 主题支持自定义模板。
如果你的项目结构非常复杂，可能需要根据实际情况调整模板代码。
修改模板后，务必重新生成文档，以使更改生效。

总结：

通过修改 Jinja2 模板，我们可以轻松地控制 Sphinx 文档侧边栏模块树的显示方式，去除完整的模块路径，使文档结构更加清晰易懂。这种方法简单有效，适用于多种 Sphinx 主题，可以显著提升文档的用户体验。

以上就是Sphinx 文档生成：去除侧边栏模块树中的完整路径的详细内容，更多请关注php中文网其它相关文章！