本文档旨在解决在使用 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 主题，可以显著提升文档的用户体验。
以上就是Sphinx 文档生成：去除侧边栏模块树中的完整路径的详细内容，更多请关注创想鸟其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1367254.html
微信扫一扫 
支付宝扫一扫 
