Sphinx documentation: split a python source into sections, using autodoc

Question

I'm using Sphinx with autodoc to document my sources. Lets say I have a file pre_processing.py , containing 3 classes. I would like to have section in the generated HTML files, like this

Main
====
Topic1
------
blabla
Here is included class1 and class2 doc

Topic2
------
blibli
Here is included class3 doc

However , all that I can manage so far is this:

Main
====
Topic1
------
blabla
Here is a link to  class1 and class2 doc

Topic2
------
blibli
Here is a link to class3 doc

Here is cdumped class1, class2 and class3

How can this be achieved please? Do I have to abandon autodoc , and fill my rst file manually ?

Answer 1

You can do that, by putting your outline (and accompanying text) into the docstring of the module itself. Let's say this is your pre_processing.py :

# yada yada license yada
"""
Main
====
Topic1
------
blabla

.. autoclass:: class1

.. autoclass:: class2

Topic2
------
blibli
Here is a link to class3 doc
"""

class class1(…):
    """
    docstring of class 1
    """

…

Then you can simply use .. automodule: in your .rst file:

.. automodule:: pre_processing

That will first read the docstring of the module and generate the documentation from there. Due to the autoclass directives in there, the classes are also documented.