Structuring documentation with sphinx autodoc

Question

So, I have two modules:

"""
Module 1
=========
"""
def foo():
    """foo doc"""

and

"""
Module 2
=========
"""
def bar():
    """bar doc"""

Then I have a rst file that goes like

*************
Some heading
*************

.. automodule:: package.module1
    :members:

.. automodule:: package.module2
    :members:

The build gives me a side bar structure like this:

[+] Some Heading
    Module 1
    foo        
    Module 2
    bar

Obviously, the headings from the module doc strings are on the same level as the members of the same module. I don't like this.

Instead I found, that moving the headings from the module doc strings to the rst file like

*************
Some heading
*************

Module 1
=========

.. automodule:: package.module1
    :members:

Module 2
=========

.. automodule:: package.module2
    :members:

gives me the structure that I expected, which is:

[+] Some Heading
    [+] Module 1
        foo 
    [+] Module 2
        func1
        bar

How can I get autodoc (or sphinx?) to turn headings in module doc strings to expandable sections in the side bar?

Answer 1

I actually also try to build html documentations from my doc- strings by using sphinx. My perceptions are the following:

This will produce an own entry on the left on a top level
============================================================

============================================================
headline will be first sub-level
============================================================


############################################################
parts will be second sub- level
############################################################

************************************************************
chapter will be the third sub- level
************************************************************

another entry on top level
============================================================

that will be shown in the following way

[x] DOCUMENT1 (containing all the lines above)
[x] This will produce an own entry on the left on a top level
    [+] headline will be first sub-level
        [+] parts will be second sub- level
            [+] chapter will be the third sub- level
[x] another entry on top level

HTH