Examples

Including a table of contents

Consider for example the following module in dummy.py:

"""
Some module
-----------

Just a dummy module with some class definition
"""


class MyClass(object):
    """Some class

    With some description"""

    def do_something(self):
        """Do something"""
        pass

    #: Any instance attribute
    some_attr = None

    #: Any other instance attribute
    some_other_attr = None


#: Some module data
large_data = 'Whatever'

The autosummary flag introduces a small table of contents. So:

.. automodule:: dummy
    :members:
    :autosummary:

produces this. And:

.. autoclass:: dummy.SomeClass
    :members:
    :autosummary:

produces this.

By default, module members are (mainly) grouped according into Functions, Classes and Data, class members are grouped into Methods and Attributes. But you can also provide alternative section names by connecting to the autodocsumm-grouper event. For example, if you include:

def example_grouper(app, what, name, obj, section, options, parent):
    import dummy
    if parent is dummy.MyClass and name == 'some_other_attr':
        return 'Alternative Section'


def setup(app):
    app.connect('autodocsumm-grouper', example_grouper)

in your conf.py, you get this.

Note that you can also include the autosummary flag in the autodoc_default_options configuration value

Including the __call__ method

Suppose you have a descriptor with a __call__ method (i.e. somewhat like a method with additional features).

"""
Some module
-----------

Just a dummy module with some class definition
"""


class CallableDescriptor(object):
    """A class defining a __call__ method"""

    def __get__(self, instance, owner):
        return self

    def __set__(self, instance, value):
        """Actually not required. We just implement it to ensure the python
        "help" function works well"""
        pass

    def __call__(self, a, b):
        """
        Caller docstring for class attribute

        Parameters
        ----------
        a: any
            dummy parameter
        b: anything else
            second dummy parameter"""
        pass


class MyClass(object):
    """Some class

    With some description"""

    do_something = CallableDescriptor()

Then, if you set autodata_content = 'both' in your conf.py you get via:

.. autoclass:: call_demo.MyClass
    :noindex:
    :members:
    :undoc-members:
class MyClass[source]

Some class

With some description

Attributes

do_something(a, b) Caller docstring for class attribute
do_something(a, b)

Caller docstring for class attribute

Parameters:
  • a (any) – dummy parameter
  • b (anything else) – second dummy parameter

Skip large data representations

You can exclude large data representations via the not_document_data and document_data configuration values.

Suppose you have a dictionary with a very large representation, e.g. in the file no_data_demo.py

#: very large object
d = dict(zip(range(100), range(100)))

which you convert to

d = {0: 0, 1: 1, 2: 2, 3: 3, 4: 4, 5: 5, 6: 6, 7: 7, 8: 8, 9: 9, 10: 10, 11: 11, 12: 12, 13: 13, 14: 14, 15: 15, 16: 16, 17: 17, 18: 18, 19: 19, 20: 20, 21: 21, 22: 22, 23: 23, 24: 24, 25: 25, 26: 26, 27: 27, 28: 28, 29: 29, 30: 30, 31: 31, 32: 32, 33: 33, 34: 34, 35: 35, 36: 36, 37: 37, 38: 38, 39: 39, 40: 40, 41: 41, 42: 42, 43: 43, 44: 44, 45: 45, 46: 46, 47: 47, 48: 48, 49: 49, 50: 50, 51: 51, 52: 52, 53: 53, 54: 54, 55: 55, 56: 56, 57: 57, 58: 58, 59: 59, 60: 60, 61: 61, 62: 62, 63: 63, 64: 64, 65: 65, 66: 66, 67: 67, 68: 68, 69: 69, 70: 70, 71: 71, 72: 72, 73: 73, 74: 74, 75: 75, 76: 76, 77: 77, 78: 78, 79: 79, 80: 80, 81: 81, 82: 82, 83: 83, 84: 84, 85: 85, 86: 86, 87: 87, 88: 88, 89: 89, 90: 90, 91: 91, 92: 92, 93: 93, 94: 94, 95: 95, 96: 96, 97: 97, 98: 98, 99: 99}

very large object

You can skip this if you specify not_document_data = ['no_data_demo.d'] in your conf.py. Then you get

d

very large object

Generating a summary table without the full documentation

Using one of the autosummary-... options (e.g. autosummary-members, see Additional flags for autodoc directives) let’s you create a summary table that points to the documentation in another point of the documentation. You should, however make sure to add the noindex flag and to add a no-members flag. For our autodocsumm module this for example then looks like:

.. automodule:: autodocsumm
    :noindex:
    :no-members:
    :autosummary:
    :autosummary-members:

which gives us

Classes

AutoSummClassDocumenter(*args) Class documentor suitable for the AutoSummDirective
AutoSummDirective(name, arguments, options, …) automodule directive that makes a summary at the beginning of the module
AutoSummModuleDocumenter(*args) Module documentor suitable for the AutoSummDirective
AutosummaryDocumenter() Abstract class for for extending Documenter methods
CallableAttributeDocumenter(directive, name) sphinx.ext.autodoc.AttributeDocumenter that uses the __call__
CallableDataDocumenter(directive, name[, indent]) sphinx.ext.autodoc.DataDocumenter that uses the __call__ attr
NoDataAttributeDocumenter(*args, **kwargs) AttributeDocumenter that prevents the displaying of large data
NoDataDataDocumenter(*args, **kwargs) DataDocumenter that prevents the displaying of large data

Functions

dont_document_data(config, fullname) Check whether the given object should be documented
setup(app) setup function for using this module as a sphinx extension

Data

member_options Options of the sphinx.ext.autodoc.ModuleDocumenter that have an

Sphinx extension that defines a new automodule directive with autosummary

The AutoSummDirective defined in this extension module allows the same functionality as the automodule and autoclass directives of the sphinx.ext.autodoc module but with an additional autosummary option. This option puts a autosummary in the style of the sphinx.ext.autosummary module at the beginning of the class or module. The content of this autosummary is automatically determined by the results of the automodule (or autoclass) directive.

This extension gives also the possibility to choose which data shall be shown and to include the docstring of the '__call__' attribute.

Generating a summary table for the module without nesting

Using the autosummary-no-nesting option, you can generate the autosummary table for a module without generating autosummary tables for members within that module. This is useful when you only want to use the autosummary table as a table of contents for a given page. For the demo module, here’s an example:

.. automodule:: dummy
    :autosummary:
    :members:
    :autosummary-no-nesting:

which gives us

Some module

Just a dummy module with some class definition

Classes

MyClass Some class

Data

large_data Some module data
class MyClass[source]

Some class

With some description

do_something()[source]

Do something

some_attr = None

Any instance attribute

some_other_attr = None

Any other instance attribute

large_data = 'Whatever'

Some module data