Structuring Sphinx autodoc documentation in Python modules with sections

Question

I'm trying to improve the structure of the documentation of my python modules.

Right now I have an Sphinx index.rst file that looks like this:

Contents:

.. toctree::
:maxdepth: 3

.. automodule:: myModule1
    :members:

.. automodule:: myModule2
    :members:

etc. This produces a HTML page that contains a long chaotic list of all my documented functions. This means that the documentation is easier to read in code, than in its HTML output.

The first improvement is easy: I can add titles and descriptions to the start of each model, so that the visual separation of modules becomes clearer in the html output. So like this:

"""
##############################################
myModule1 Title
##############################################
Description of myModule1.
"""

etc. But now I'd like to take this one step further by separating my modules into sections that have their own section titles and descriptions that belong to a subset of the module's functions. I tried the following:

"""
##############################################
myModule1 Title
##############################################
Description of myModule1.
"""
... # meaning import statements etc
"""
**********************************************
First Section title
**********************************************
Some descriptive text
"""
def myFunction1()
    """ function doc """
    ... # meaning the actual function implementation

def myFunction2()
    """ function doc """
    ... # meaning the actual function implementation

"""
**********************************************
Second Section title
**********************************************
Some descriptive text
"""
def myFunction3()
    """ function doc """
    ...  # meaning the actual function implementation

def myFunction4()
    """ function doc """
    ...  # meaning the actual function implementation

But this leads to a:

'SEVERE: Unexpected section title or transition.'

error when running make HTML .

So how can I get the desired structure without moving documentation away from the code it documents?

Answer 1

So how can I get the desired structure without moving documentation away from the code it documents?

Stop using automodule and use autoclass/autofunction instead? That way you can craft and reorganise your end document however you want without messing with the Python-level sources, and the docstrings remain the proper source of truth.

Alternatively, split your modules into sub-modules which each gets autodocumented and can have a formatted module-level docstring. Incidentally you probably want to configure autodoc_member_order as it's alphabetical by default (and thus will reorder everything). bysource will show the autodocumented members in whatever order you've written them in your source file.

An other alternative would be to swap the entire thing around and write the modules in literate / doctest form. I don't think there's good standard support for this but doctest might have utility functions which let you convert a "literate document" into something approaching an importable module.