CODEWITHSUNDEEP
pythonpython-sphinx
scphantm
scphantm

Reputation: 4543

automodule to generate toc in sphinx documents

In Sphinx, is there a way to get the automodule directive to generate a TOC of the members in the class?

Right now I have

.. Contents::

.. topic:: Abstract

   bla bla bla

.. automodule:: ServerCommHandler
    :members:
    :private-members:
    :special-members:
    :show-inheritance:
    :inherited-members:

which works fine, but this module has a lot of methods in it and a toc pointing to the method would be really nice.

Upvotes: 7

Views: 2986

Answers (2)

coldfix
coldfix

Reputation: 7102

The autodocsumm extension will allow autodoc directives (automodule, autoclass) to automatically add summary tables like those of the builtin autosummary extension.

It can be used as follows:

pip install autodocsumm

Then edit your conf.py to add the extension:

extensions = [
    'sphinx.ext.autodoc',
    ...,
    'autodocsumm',
]

and add an :autosummary: option to your autodoc directives, e.g.:

.. automodule: foo.bar
    :autosummary:

If you want to have autosummary in effect for all your autodoc directives without explicitly adding them, you can do so from the conf.py as follows:

autodoc_default_options = {
    'autosummary': True,
}

This is particularly helpful if you dynamically generate your API pages with sphinx-apidoc which is not easily configurable to add :autosummary:.

Full example of a conf.py that autogenerates all API pages:

def setup(app):
    from sphinx.ext import apidoc
    app.connect('builder-inited', lambda _: apidoc.main([
        '-o', './api', '-d2', '-feMT', '../src/PROJECT',
    ]))

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'autodocsumm',
]


autodoc_default_options = {
    'autosummary': True,
}

autodata_content = 'both'

Upvotes: 7

Steven Almeroth
Steven Almeroth

Reputation: 8202

How about toctree.

.. toctree::

   ServerCommHandler

Upvotes: -4

Related Questions