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