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
  • autosummary-no-nesting

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

The new additional flag autosummary-no-nesting only generates autosummary tables for a module, but not for members within. See Generating a summary table for the module without nesting.

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