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.

.. 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