Sphinx 文档树没有模块的完整路径

Question

我正在尝试使用带有 autodoc 和 autosummary 扩展的 sphinx 创建自动化文档。我也在使用 pydata_sphinx_theme。

我的目标是自动创建一个对象树（现在让我们继续使用 python 函数），它将显示在文档的主侧边栏中。

模板（见下图）完成了这项工作，但它始终显示每个功能的完整路径 - 例如

my_package.my_python_module1.function_A

。 目标是摆脱整个路径并只看到结束对象。

Code structure:
├───my_package
│   └───my_python_module1 (contains function_A)
│   └───my_directory
│       └───my_python_module2 (contains function_B)


Generated documentation tree:
├───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

Desired documentation tree
├───my_package
│   └───my_python_module1
│          └───function_A
│   └───my_directory
│       └───my_python_module2
│              └───function_B

推荐的选项之一是在 conf.py 中使用

add_module_names = False

- 这不适用于 pydata_sphinx_theme。

还在代码中使用“全名”（例如用“名称”替换）也只能部分解决问题。

custom-module-template.rst 的完整模板代码：

{{ fullname | 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 %}

那么问题是：如何调整模板以摆脱完整路径？

Answer 1

昨天花了几个小时寻找解决方案，因为目录中的完整路径在我的情况下看起来非常丑陋。 似乎为我解决这个问题的解决方案是添加

:nosignatures:

到我想要阻止完整路径的块（即模块和类标题）。我一直使用的主题是

sphinx_book_theme

例如：

.. rubric:: Modules

.. autosummary::
   :toctree:
   :template: custom-module-template.rst
   :nosignatures:                             <--- This line was added
   :recursive: