Sphinx with autodoc "duplicate object description" Warning when grouping members into separate files

Question

I have some functions in a module which I would like to break up into two groups in my documentation. I have three files:

my_mod.rst

my_mod
======
.. automodule:: my_mod
   :no-members:

.. toctree::
   :maxdepth: 1

   my_mod/group1
   my_mod/group2

group1.rst

group1
======

.. automodule:: my_mod
   :members: add, subtract

group2.rst

group2
======

.. automodule:: my_mod
   :members: multiply, divide

I have to use .. automodule:: my_mod in each. In my_mod.rst so it displays the module docstring and in the other files to identify the :members: that I want to be displayed. However, this causes multiple errors when generating the HTML files, like:

/pathto/my_mymod.rst:2: WARNING: duplicate object description of my_mod, other instance in my_mod/group1, use :noindex: for one of them

If I add :noindex: though, I can no longer link to these functions from elsewhere in the documentation so that is not a solution for me.

Can I avoid these error messages without losing any functionality? Also, this seems to be working as I hoped (except for the error messages), but are there any potential pitfalls to referencing the same module multiple times?

Answer 1

An alternative is to use autofunction.

group1
======

.. currentmodule:: my_mod

.. autofunction:: add
.. autofunction:: subtract

and

group2
======

.. currentmodule:: my_mod

.. autofunction:: multiply
.. autofunction:: divide