# API Reference

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

class AutoDocSummDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

  Bases: `SphinxDirective`

  A directive to generate an autosummary.

  Usage:

      .. autoclasssumm:: <Class>

      .. automodsumm:: <module>

      .. autoexceptionsumm:: <ExceptionClass>

  The directive additionally supports all options of the `autoclass`, `automod`, or `autoexception` directive respectively. Sections can be a list of section titles to be included. If ommitted, all sections are used.

  has_content = False

    May the directive have content?

  option_spec = {}

    Mapping of option names to validator functions.

  optional_arguments = 0

    Number of optional arguments after the required arguments.

  required_arguments = 1

    Number of required directive arguments.

class AutoSummClassDocumenter(*args: Any)

  Bases: `ClassDocumenter`, `AutosummaryDocumenter`

  Class documentor with autosummary tables for its members.

  This class has the same functionality as the base `sphinx.ext.autodoc.ClassDocumenter` class but with an additional autosummary option to provide the ability to provide a summary of all methods and attributes. It’s priority is slightly higher than the one of the ClassDocumenter

  Methods:

  `add_content`(*args, **kwargs) | Add content from docstrings, attribute documentation and user.

  Attributes:

  `member_sections` | `dict` that includes the autosummary sections
  `option_spec` | original option_spec from `sphinx.ext.autodoc.ClassDocumenter` but with additional autosummary boolean option
  `priority` | slightly higher priority than `sphinx.ext.autodoc.ClassDocumenter`

  add_content(*args, **kwargs)

    Add content from docstrings, attribute documentation and user.

  member_sections: dict = {20: 'Classes', 50: 'Methods', 60: 'Attributes'}

    `dict` that includes the autosummary sections

    This dictionary defines the sections for the autosummmary option. The values correspond to the `sphinx.ext.autodoc.Documenter.member_order` attribute that shall be used for each section.

  option_spec: ClassVar[OptionSpec] = {'autosummary': <function bool_option>, 'autosummary-exclude-members': <function exclude_members_option>, 'autosummary-force-inline': <function bool_option>, 'autosummary-inherited-members': <function inherited_members_option>, 'autosummary-members': <function members_option>, 'autosummary-no-nesting': <function bool_option>, 'autosummary-no-titles': <function bool_option>, 'autosummary-nosignatures': <function bool_option>, 'autosummary-private-members': <function members_option>, 'autosummary-sections': <function list_option>, 'autosummary-special-members': <function members_option>, 'autosummary-undoc-members': <function bool_option>, 'class-doc-from': <function class_doc_from_option>, 'exclude-members': <function exclude_members_option>, 'inherited-members': <function inherited_members_option>, 'member-order': <function member_order_option>, 'members': <function members_option>, 'no-index': <function bool_option>, 'noindex': <function bool_option>, 'private-members': <function members_option>, 'show-inheritance': <function bool_option>, 'special-members': <function members_option>, 'undoc-members': <function bool_option>}

    original option_spec from `sphinx.ext.autodoc.ClassDocumenter` but with additional autosummary boolean option

  priority = 15.1

    slightly higher priority than `sphinx.ext.autodoc.ClassDocumenter`

class AutoSummExceptionDocumenter(*args: Any)

  Bases: `ExceptionDocumenter`, `AutosummaryDocumenter`

  Exception Documenter with autosummary tables for its members.

  This class has the same functionality as the base `sphinx.ext.autodoc.ExceptionDocumenter` class but with an additional autosummary option to provide the ability to provide a summary of all methods and attributes. It’s priority is slightly higher than the one of the ExceptionDocumenter

  Methods:

  `add_content`(*args, **kwargs) | Add content from docstrings, attribute documentation and user.

  Attributes:

  `member_sections` | `dict` that includes the autosummary sections
  `option_spec` | original option_spec from `sphinx.ext.autodoc.ExceptionDocumenter` but with additional autosummary boolean option
  `priority` | slightly higher priority than `sphinx.ext.autodoc.ExceptionDocumenter`

  add_content(*args, **kwargs)

    Add content from docstrings, attribute documentation and user.

  member_sections: dict = {10: 'Classes', 50: 'Methods', 60: 'Attributes'}

    `dict` that includes the autosummary sections

    This dictionary defines the sections for the autosummmary option. The values correspond to the `sphinx.ext.autodoc.Documenter.member_order` attribute that shall be used for each section.

  option_spec: ClassVar[OptionSpec] = {'autosummary': <function bool_option>, 'autosummary-exclude-members': <function exclude_members_option>, 'autosummary-force-inline': <function bool_option>, 'autosummary-inherited-members': <function inherited_members_option>, 'autosummary-members': <function members_option>, 'autosummary-no-nesting': <function bool_option>, 'autosummary-no-titles': <function bool_option>, 'autosummary-nosignatures': <function bool_option>, 'autosummary-private-members': <function members_option>, 'autosummary-sections': <function list_option>, 'autosummary-special-members': <function members_option>, 'autosummary-undoc-members': <function bool_option>, 'class-doc-from': <function class_doc_from_option>, 'exclude-members': <function exclude_members_option>, 'inherited-members': <function inherited_members_option>, 'member-order': <function member_order_option>, 'members': <function members_option>, 'no-index': <function bool_option>, 'noindex': <function bool_option>, 'private-members': <function members_option>, 'show-inheritance': <function bool_option>, 'special-members': <function members_option>, 'undoc-members': <function bool_option>}

    original option_spec from `sphinx.ext.autodoc.ExceptionDocumenter` but with additional autosummary boolean option

  priority = 20.1

    slightly higher priority than `sphinx.ext.autodoc.ExceptionDocumenter`

class AutoSummModuleDocumenter(*args: Any)

  Bases: `ModuleDocumenter`, `AutosummaryDocumenter`

  Module documentor with autosummary tables of its members.

  This class has the same functionality as the base `sphinx.ext.autodoc.ModuleDocumenter` class but with an additional autosummary. It’s priority is slightly higher than the one of the ModuleDocumenter.

  Methods:

  `add_content`(*args, **kwargs) | Add content from docstrings, attribute documentation and user.

  Attributes:

  `member_sections` | `dict` that includes the autosummary sections
  `option_spec` | original option_spec from `sphinx.ext.autodoc.ModuleDocumenter` but with additional autosummary boolean option
  `priority` | slightly higher priority than `sphinx.ext.autodoc.ModuleDocumenter`

  add_content(*args, **kwargs)

    Add content from docstrings, attribute documentation and user.

  member_sections: dict = {10: 'Exceptions', 20: 'Classes', 30: 'Functions', 40: 'Data'}

    `dict` that includes the autosummary sections

    This dictionary defines the sections for the autosummmary option. The values correspond to the `sphinx.ext.autodoc.Documenter.member_order` attribute that shall be used for each section.

  option_spec: ClassVar[OptionSpec] = {'autosummary': <function bool_option>, 'autosummary-exclude-members': <function exclude_members_option>, 'autosummary-force-inline': <function bool_option>, 'autosummary-ignore-module-all': <function bool_option>, 'autosummary-imported-members': <function bool_option>, 'autosummary-inherited-members': <function inherited_members_option>, 'autosummary-members': <function members_option>, 'autosummary-no-nesting': <function bool_option>, 'autosummary-no-titles': <function bool_option>, 'autosummary-nosignatures': <function bool_option>, 'autosummary-private-members': <function members_option>, 'autosummary-sections': <function list_option>, 'autosummary-special-members': <function members_option>, 'autosummary-undoc-members': <function bool_option>, 'deprecated': <function bool_option>, 'exclude-members': <function exclude_members_option>, 'ignore-module-all': <function bool_option>, 'imported-members': <function bool_option>, 'inherited-members': <function inherited_members_option>, 'member-order': <function member_order_option>, 'members': <function members_option>, 'no-index': <function bool_option>, 'no-value': <function bool_option>, 'noindex': <function bool_option>, 'platform': <function identity>, 'private-members': <function members_option>, 'show-inheritance': <function bool_option>, 'special-members': <function members_option>, 'synopsis': <function identity>, 'undoc-members': <function bool_option>}

    original option_spec from `sphinx.ext.autodoc.ModuleDocumenter` but with additional autosummary boolean option

  priority = 0.1

    slightly higher priority than `sphinx.ext.autodoc.ModuleDocumenter`

class AutosummaryDocumenter

  Bases: `object`

  Abstract class for for extending Documenter methods

  This classed is used as a base class for Documenters in order to provide the necessary methods for generating the autosummary.

  Methods:

  `add_autosummary`([relative_ref_paths]) | Add the autosammary table of this documenter.
  `get_grouped_documenters`([all_members]) | Method to return the member documenters

  Attributes:

  `filter_funcs` | List of functions that may filter the members
  `grouper_funcs` | Grouper functions

  add_autosummary(relative_ref_paths=False)

    Add the autosammary table of this documenter.

    Parameters:

      relative_ref_paths (bool) – Use paths relative to the current module instead of absolute import paths for each object

  filter_funcs = []

    List of functions that may filter the members

  get_grouped_documenters(all_members=False)

    Method to return the member documenters

    This method is somewhat like a combination of the `sphinx.ext.autodoc.ModuleDocumenter.generate()` method and the `sphinx.ext.autodoc.ModuleDocumenter.document_members()` method. Hence it initializes this instance by importing the object, etc. and it finds the documenters to use for the autosummary option in the same style as the document_members does it.

    Returns:

      dictionary whose keys are determined by the `member_sections` dictionary and whose values are lists of tuples. Each tuple consists of a documenter and a boolean to identify whether a module check should be made describes an attribute or not.

    Return type:

      dict

    Notes

    If a `sphinx.ext.autodoc.Documenter.member_order` value is not in the `member_sections` dictionary, it will be put into an additional Miscellaneous section.

  grouper_funcs = []

    Grouper functions

class CallableAttributeDocumenter(directive: DocumenterBridge, name: str, indent: str = '')

  Bases: `AttributeDocumenter`

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

  Methods:

  `format_args`() | Format the argument signature of self.object.
  `get_doc`(*args, **kwargs) | Reimplemented to include data from the call method

  Attributes:

  `priority` | slightly higher priority than `sphinx.ext.autodoc.AttributeDocumenter`

  format_args()

    Format the argument signature of self.object.

    Should return None if the object does not have a signature.

  get_doc(*args, **kwargs)

    Reimplemented to include data from the call method

  priority = 10.1

    slightly higher priority than `sphinx.ext.autodoc.AttributeDocumenter`

class CallableDataDocumenter(directive: DocumenterBridge, name: str, indent: str = '')

  Bases: `DataDocumenter`

  `sphinx.ext.autodoc.DataDocumenter` that uses the __call__ attr

  Methods:

  `format_args`() | Format the argument signature of self.object.
  `get_doc`(*args, **kwargs) | Reimplemented to include data from the call method

  Attributes:

  `priority` | slightly higher priority than `sphinx.ext.autodoc.DataDocumenter`

  format_args()

    Format the argument signature of self.object.

    Should return None if the object does not have a signature.

  get_doc(*args, **kwargs)

    Reimplemented to include data from the call method

  priority = -9.9

    slightly higher priority than `sphinx.ext.autodoc.DataDocumenter`

class NoDataAttributeDocumenter(*args, **kwargs)

  Bases: `CallableAttributeDocumenter`

  AttributeDocumenter that prevents the displaying of large data

  Attributes:

  `priority` | slightly higher priority as the one of the CallableAttributeDocumenter

  priority = 10.2

    slightly higher priority as the one of the CallableAttributeDocumenter

class NoDataDataDocumenter(*args, **kwargs)

  Bases: `CallableDataDocumenter`

  DataDocumenter that prevents the displaying of large data

  Attributes:

  `priority` | slightly higher priority as the one of the CallableDataDocumenter

  priority = -9.8

    slightly higher priority as the one of the CallableDataDocumenter

dont_document_data(config, fullname)

  Check whether the given object should be documented

  Parameters:

    - config (sphinx.Options) – The configuration

    - fullname (str) – The name of the object

  Returns:

    Whether the data of fullname should be excluded or not

  Return type:

    bool

list_option(option)

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

member_options = {'exclude-members', 'ignore-module-all', 'imported-members', 'inherited-members', 'members', 'private-members', 'special-members', 'undoc-members'}

  Options of the `sphinx.ext.autodoc.ModuleDocumenter` that have an effect on the selection of members for the documentation

setup(app)

  setup function for using this module as a sphinx extension