4

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?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
dshanahan
  • 676
  • 5
  • 12
  • Why did you indent `toctree`, and place it below the module you want to autodoc? I think it should be dedented and above the module. – Steve Piercy Apr 22 '20 at 22:48
  • @StevePiercy I'll agree with the indent being unnecessary, but I want the `toctree` below the module docstring so that is why it is ordered that way. – dshanahan Apr 23 '20 at 04:11
  • Have you tried following the warning's advice, then [cross-reference arbitrary locations with `:ref:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role)? You might also try using the [`index` directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-index) to ensure it appears in your documentation's index. – Steve Piercy Apr 23 '20 at 05:20

1 Answers1

4

An alternative is to use autofunction.

group1
======

.. currentmodule:: my_mod

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

and

group2
======

.. currentmodule:: my_mod

.. autofunction:: multiply
.. autofunction:: divide
mzjn
  • 48,958
  • 13
  • 128
  • 248