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 ?

I'm not sure I understand the question, but maybe it will work as you want it if you use autoclass (which produces documentation for a single class) instead of automodule. — mzjn
yes if i use autoclass, then i can edit the rst file and build my sections as i want with autoclass. But i would like to define the sections inside the python sources, somehow. Liek saying "this class belong to section x, this one to y, etc". — Napseis

Jonas Schäfer Jonas Schäfer · Accepted Answer · 2016-10-14T07:10:02

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.

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

1 Answers