pythonpython-sphinxnumpydoc

Sphinx autosummary produces two summaries for each class


I'm using Sphinx+autodoc+autosummary to generate documentation for my project (mrpy).

I am doing a two-layer summary, where in the index.rst I have (minimally)

mrpy
====

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

   mrpy.stats
   <other modules...>

I use a custom template for the module-level autosummary as you can see. I do this so that on the module-level summary, I also get a summary of the objects within the module, which each link to their own pages. For reference, my modules.rst file is

{{ 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 contains just three classes, which get summarised beautifully when following the link in the table produced on the index page. When following the link to one of those classes, I use another custom template, 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 %}

However, the page for this class contains the title, as expected, the class docstring, as expected, but two tabulated summaries of the methods and attributes of the class.

Anyone know how to get rid of one of the redundant tables?


Solution

  • It seems that the answer is that numpydoc screws around with autosummary. Adding numpydoc_show_class_members=False to the conf.py fixes the problem. Solution found here: https://github.com/phn/pytpm/issues/3#issuecomment-12133978