# 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

    class MyException(object):
        """Some Exception

        With some description"""

        def do_something_exceptional(self):
            """Do something exceptional"""
            pass

        #: Any instance attribute
        some_exception_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.MyClass
        :members:
        :autosummary:

produces this, and for exceptions:

    .. autoexception:: dummy.MyException
        :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

  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

> http://www.apache.org/licenses/LICENSE-2.0

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.
`AutoSummExceptionDocumenter`(*args) | Exception Documenter 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
`MyException`() | Some Exception

Data:

`large_data` | Some module data

class MyClass

  Some class

  With some description

  do_something()

    Do something

  some_attr = None

    Any instance attribute

  some_other_attr = None

    Any other instance attribute

class MyException

  Some Exception

  With some description

  do_something_exceptional()

    Do something exceptional

  some_exception_attr = None

    Any 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
`MyException` | Some Exception

Data:

`large_data` | Some module data

class MyClass

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

    Do something

  some_attr = None

    Any instance attribute

  some_other_attr = None

    Any other instance attribute

class MyException

  Some Exception

  With some description

  Methods:

  `do_something_exceptional` | Do something exceptional

  Attributes:

  `some_exception_attr` | Any instance attribute

  do_something_exceptional()

    Do something exceptional

  some_exception_attr = None

    Any 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`, `autoexceptionsumm` 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

  Some class

  This will be after the autosummary table.

  do_something()

    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

  Some class

  This will be after the autosummary table.

  Attributes:

  `some_attr` | Any instance attribute

  do_something()

    Do something

  some_attr = None

    Any instance attribute