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

Sphinx extension that defines new auto documenters with autosummary.

The AutoSummModuleDocumenter and AutoSummClassDocumenter classes defined here enable an autosummary-style listing of the corresponding members.

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

Disclaimer

Copyright 2016-2019, Philipp S. Sommer

Copyright 2020-2021, Helmholtz-Zentrum Hereon

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Classes:

AutoDocSummDirective(name, arguments, ...)

A directive to generate an autosummary.

AutoSummClassDocumenter(*args)

Class documentor with autosummary tables for its members.

AutoSummModuleDocumenter(*args)

Module documentor with autosummary tables of its members.

AutosummaryDocumenter()

Abstract class for for extending Documenter methods

CallableAttributeDocumenter(directive, name)

sphinx.ext.autodoc.AttributeDocumenter that uses the __call__ attr

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

list_option(option)

Transform a string to a list by splitting at ;;.

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 effect on the selection of members for the documentation

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

Generating a summary table without signatures

Using the autosummary-nosignatures option, you can generate the autosummary table for a module that will not include function signatures. This is useful for giving a high-level overview of the function name and description. For the demo module, here’s an example:

.. automodule:: dummy
    :members:
    :autosummary:
    :autosummary-nosignatures:

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

Methods:

do_something

Do something

Attributes:

some_attr

Any instance attribute

some_other_attr

Any other instance attribute
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

Select the sections to document

You can select, which sections to document. If you only want the Methods section of a class, you can specify:

.. autoclass:: dummy.MyClass
    :members:
    :autosummary:
    :autosummary-sections: Methods

Multiple sections might be separated by ;;, e.g. :autosummary-sections: Methods ;; Attributes.

This also works for the autoclasssumm and automodulesumm directives, e.g.:

.. autoclasssumm:: dummy.SomeClass
    :autosummary-sections: Methods

Positioning of the autosummary table

By default, the autosummary tables are put at the end of the docstring sections for classes and methods, i.e. something like:

class-name
class-docstring
autosummary-tables
class-members

You can customize this positioning by calling the .. autoclasssumm:: directive inside the class docstring, e.g.

class MyClass(object):
    """Some class

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

    This will be after the autosummary table.
    """

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

    #: Any instance attribute
    some_attr = None

Documenting this, with .. autoclass:: MyClass creates

class MyClass[source]

Some class

This will be after the autosummary table.

do_something()[source]

Do something

some_attr = None

Any instance attribute

Note that this omits the Attributes section as we specified the :autosummary-sections: options here. If you want to list this section anyway at the end of the docstring, you can use the autosummary-force-inline option, e.g.:

.. autoclass:: inline_autoclasssumm.MyClass
    :members:
    :autosummary-force-inline:
    :autosummary-sections: Attributes
class MyClass[source]

Some class

This will be after the autosummary table.

Attributes:

some_attr

Any instance attribute
do_something()[source]

Do something

some_attr = None

Any instance attribute