Sphinx recursive autosummary: duplicate objects warning, :noindex: option breaks links

Question

I am using Sphinx to generate the API documentation for a python package. At the moment I get the warning

WARNING: duplicate object description of package.module.submodule.Class.function other instance in generated/package.module.submodule, use :noindex: for one of them

for basically every function resulting in over 300 warnings.

My RST files look like this:

api.rst:

.. autosummary::
    :toctree: generated
    :recursive:
    :template: module-template.rst
    
    package

module-template.rst:

{{ fullname | escape | underline}}

{% block modules %}
{% if modules %}
.. rubric:: {{ _('Submodules') }}

.. autosummary::
   :toctree:
   :template: module-template.rst
   :recursive:
   {% for item in modules %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

Module Description
^^^^^^^^^^^^^^^^^^

.. automodule:: {{ fullname }}
   :members:

   {% block attributes %}
   {% if attributes %}
   .. rubric:: {{ _('Module Attributes') }}

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

   {% block functions %}
   {% if functions %}
   .. rubric:: {{ _('Functions') }}

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

   {% block classes %}
   {% if classes %}
   .. rubric:: {{ _('Classes') }}

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

   {% block exceptions %}
   {% if exceptions %}
   .. rubric:: {{ _('Exceptions') }}

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

class-template.rst:

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}
   :members:
   :show-inheritance:
   :inherited-members:

   {% block methods %}

   {% if methods %}
   .. rubric:: {{ _('Methods') }}

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

   {% block attributes %}
   {% if attributes %}
   .. rubric:: {{ _('Attributes') }}

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

I tried adding the :noindex: flag to module-template.rst as an option for the .. automodule:: directive like this:

.. automodule:: {{ fullname }}
   :members:
   :noindex:

This did get rid of the warnings, but it led to the problem, that the modules and functions (which right now are being displayed in a table at the top of the module page) became unclickable and according to some googleing this also removes the possibilities to link to those entries in general.

The only solutions I have found so far have suggested to use the .. autofunction:: directive instead of .. autosummary::, however this is not really a viable option for me due to the size of the package and the amount of manual work involved with this.

Is it possible to get rid of this warning without breaking the links to modules and functions?

Answer 1

I am writing here because I can not comment.

I am facing the same issue. I.e. class, function, ... links are not generated on the module page, did you report this issue on GitHub ?

A workaround:

Use https://github.com/readthedocs/sphinx-autoapi for your API reference. It is straightforward to set up:

Add the extension to conf.py

extensions += ["autoapi.extension"]

And also set autoapi_dirs variable in the same file:

# Repo Structure:
# reponame
# - docs/
#   - source/
#     - conf.py
#     - ...
#   - build/
# - yourpkg/
#   - __init__.py
#   - module.py
autoapi_dirs = ['../../yourpkg']

Next time you run make html an API Reference section will be automatically generated.