Can the Sphinx "automodule" be told to automatically insert section breaks between members?

Question

This question is inspired by the Mayavi documentation, which has nice section breaks with the name of the function being described between each module member.

My .rst right now just looks like:

SQLAlchemy Tables
**********************************

.. automodule:: ExperimentOrganizer.table_def
    :members:

(With all of the documentation formatted text in the module itself.)

Is there a simple way to indicate that I'd like to have section headers inserted between each member in :members:? If not, how did the Mayavi folks do it?

Alodie

Answer 1

Can the Sphinx "automodule" be told to automatically insert section breaks between members?

No. There is no magic option to automodule or something like that. If you want section headers then you'll have to add them yourself (perhaps by using a script) to the reST source. See also the answer to this similar question: Sphinx customizing autoclass output.

The Mayavi documentation that you refer to is not created with autodoc. The functions are documented using the function directive (not autofunction). Click on "Show Source" to see the reST markup.

Variance

Answer 2

There is a lengthy and cumbersome workaround: You first document the class without any members, then you insert the section header yourself, and then you document the members one by one.

Example using the class from https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html, which also states the directives:

.. currentmodule:: module.name

Documentation
-------------

.. autoclass:: Noodle

Attributes
----------

.. autoattribute:: Noodle.eat
.. autoattribute:: Noodle.slurp
.. autoamethod:: Noodle.boil

Swell