本文档旨在解决在使用 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 文件。
重新生成 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 主题，可以显著提升文档的用户体验。
