Sphinx customizing autoclass output

Question

I have a module with several classes. Currently I am using ..automodule to document the module. I'd like each class to have its own header section with the class name. I could achieve this by replacing ..automodule foo with:

Bar
===

..autoclass foo.Bar

Baz
===

..autoclass foo.Baz

...

However, that would require me to manually list every class in every module I do this for. What is the best way to customize the content generated by automodule?

Answer 1

Sphinx is not as straightforward to use as Epydoc or Doxygen for generating API documentation from source code. It is a dfferent kind of tool.

Sphinx works on .rst (reStructuredText) files, and if you want each class to have its own heading with the class name, you have to add the headings yourself and use .. autoclass::. It cannot be done with just .. automodule::. Yes, this is inconvenient (similar sentiments are expressed here). See also this answer and this answer.

The problem can be mitigated by a script that walks through the Python code and generates .rst output. Sphinx already comes with such a script, sphinx-apidoc. However, it does not produce any .. autoclass:: directives, only .. automodule::.

Here is another script that can output .. autoclass::: https://github.com/PyMVPA/PyMVPA/blob/master/tools/apigen.py. Maybe you can use that.