Configuration of the sphinx extension

The module provides 3 additional configuration values, one event and new flags for the autodoc directives autoclass and automodule.

Additional flags for autodoc directives

The most important new flag for the autoclass and automodule directives is the autosummary flag. If you want to have an automatically generated summary to your class or module, you have to add this flag, e.g. via:

.. autodoc:: MyClass
    :autosummary:

or in the autodoc_default_options configuration value of sphinx via

autodoc_default_options = {'autosummary': True}

See also the usage in the Examples section.

The other additional flags lets you control what should be in the autosummary table: these are

autosummary-private-members
autosummary-undoc-members
autosummary-inherited-members
autosummary-special-members
autosummary-exlude-members
autosummary-imported-members
autosummary-ignore-module-all
autosummary-members

They are essentially the same as the options for autodoc (i.e. private-members or members), but they only affect the autosummary table (see the example in Generating a summary table without the full documentation).

autosummary-no-nesting: The new additional flag autosummary-no-nesting only generates autosummary tables for a module, but not for members within. See example about Generating a summary table for the module without nesting.
autosummary-sections: Select which sections to generate the autosummary for. Usage is like :autosummary-sections: Methods ;; Attributes. When omitted, all sections are generated. See the example about Select the sections to document
autosummary-no-titles: Do not add section titles above each autosummary table
autosummary-force-inline: Force adding the autosummary, even it is already contained in the class or module docstring. See the example about Positioning of the autosummary table
autosummary-nosignatures: Do not show function signatures in the summary table.

Directives

.. autoclasssumm::

This class generates the autosummary tables for the given class. You can use the same options as for the autoclass directive. You can select a specific section and omit the title via:

.. autoclasssumm:: MyClass
    :autosummary-sections: Methods
    :autosummary-no-titles:

By default, this directives also sets the :members: option unless you specify :no-members.

.. autoexceptionsumm::: The same as the autoclasssumm directive, just for an Exception subclass.

.. automodulesumm::: The same as the autoclasssumm directive, just for a module.

Configuration values and events

autodocsumm-grouper(app, what, name, obj, section, parent)

Emitted when autodocsumm has to determine the section for a member in the table of contents. If the return value is None, the given section will be used.

Parameters:

app – the Sphinx application object
what – the type of the object which the docstring belongs to (one of "module", "class", "exception", "function", "method", "attribute")
name – the fully qualified name of the object
obj – the member object
section – The section title that would be given to the object automatically (one of "Classes", "Exceptions", "Functions", "Methods", "Attributes", "Data")
parent – The parent object holding the member obj

autodata_content

As you can include the __init__ method documentation for via the autoclass_content configuration value, this configuration value lets you include the documentation from the __call__ method. Possible values are

class: To only use the class documentation
call: To only use the documentation from the __call__ method
both: To use the documentation from all.

The default is 'call'

document_data: To include the string representation of specific data objects. You may provide a list of fully qualified object names (e.g. in the form of 'zipfile.ZipFile') or True or False

not_document_data: To exclude the string representation of specific data objects. You may provide a list of fully qualified object names (e.g. in the form of 'zipfile.ZipFile') or True or False

autodocsumm_section_sorter

When True the summarizing sections will be sorted alphanumerically by their section title. Alternatively a callable can be set that is passed to sorted() as key argument to sort the the summary sections by their name. The default value is None. Example usage with a tuple that defines an arbitrary order:

sections_order = ("Public methods", "Attributes", "Private methods")
autodocsumm_section_sorter = lambda title: sections_order.index(title)

An example for cases that only ensures that “Constructors” are always listed first and “Attributes” while not failing when encountering undefined section weights:

section_weights = {"Attributes": 100, "Constructors": -100}
autodocsumm_section_sorter = lambda title: sections_weights.get(title, 0)