I’m trying to organize the contents of a module under subsections. I was surprised to see that section headers are allowed within an automodule directive, which works well for my purposes. I’m controlling the order of members by inserting explicit autofunction and autoclass directives under the correct headings.

My .rst file looks like this:

mymodule
========

.. automodule:: mymodule
    :members:

    Section A
    ---------

    .. autofunction:: foo

    .. autoclass:: Foo

    Section B
    ---------

    .. autofunction:: bar

    Other
    -----

This almost works exactly the way I want – the module’s docstring is included first, then each explicitly added function or class in the different subsections, then the members inserted automatically by automodule fall into the “Other” section.

The problem is that Sphinx inserts all public members of the module again, even if they previously appeared an an explicit autofunction or autoclass. My expectation was that Sphinx would recognize that these members had already been included in the automodule and avoid adding duplicates. Is it possible to get this behavior?

The two workarounds I’ve come up with aren’t completely satisfactory:

• Listing the remaining members explicitly under :members:. This kind of defeats the purpose of the “Other” section, which is that all public members of the module will always be included even if I haven’t updated the documentation source file.
• Adding the names of every explicitly included member under :exclude-members: so they won’t be added again. This works and is what I’m currently doing, but the list gets very long and it’s another thing to remember.