Sphinx autosummary 为每个 class 生成两个摘要

Question

我正在使用 Sphinx+autodoc+autosummary 为我的项目生成文档 (mrpy)。

我正在做一个 two-layer 总结，在 index.rst 我有（最少）

mrpy
====

.. autosummary::
   :toctree: _autosummary
   :template: modules.rst

   mrpy.stats
   <other modules...>

如您所见，我为 module-level 自动摘要使用自定义模板。我这样做是为了在 module-level 摘要上，我还获得了模块内 objects 的摘要，每个 link 都有自己的页面。作为参考，我的 modules.rst 文件是

{{ fullname }}
{{ underline }}

.. automodule:: {{ fullname }}

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

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

   {% block classes %}
   {% if classes %}
   .. rubric:: Classes

   .. autosummary::
      :toctree: {{ objname }}
      :template: class.rst
   {% for item in classes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block exceptions %}
   {% if exceptions %}
   .. rubric:: Exceptions

   .. autosummary::
   {% for item in exceptions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

mrpy.stats 仅包含三个 class，当在索引页上生成的 table 中跟随 link 时，它们得到了很好的总结。当跟随 link 到其中一个 classes 时，我使用了另一个自定义模板，class.rst:

{{ fullname }}
{{ underline }}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}

   {% block methods %}

   {% if methods %}
   .. rubric:: Methods

   .. autosummary::
      :toctree: {{ objname }}
   {% for item in methods %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block attributes %}
   {% if attributes %}
   .. rubric:: Attributes

   .. autosummary::
      :toctree: {{ objname }}
   {% for item in attributes %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

然而，这个 class 的页面包含标题，正如预期的那样，class 文档字符串，但是 two class 的方法和属性。

有人知道如何删除其中一个多余的 table 吗？

Answer 1

看来答案是 numpydoc 搞砸了自动摘要。将 numpydoc_show_class_members=False 添加到 conf.py 可以解决问题。在此处找到解决方案：https://github.com/phn/pytpm/issues/3#issuecomment-12133978

Sphinx autosummary 为每个 class 生成两个摘要

Sphinx autosummary produces two summaries for each class

python

python-sphinx

numpydoc