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

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)[source]

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: The type of the None singleton.

option_spec = {}: The type of the None singleton.

optional_arguments = 0: The type of the None singleton.

required_arguments = 1: The type of the None singleton.

class AutoSummClassDocumenter(*args: Any)[source]

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`	The type of the None singleton.
`option_spec`	The type of the None singleton.
`priority`	The type of the None singleton.

add_content(*args, **kwargs)[source]: Add content from docstrings, attribute documentation and user.

member_sections: dict = {20: 'Classes', 50: 'Methods', 60: 'Attributes'}: The type of the None singleton.

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>, 'no-index-entry': <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>}: The type of the None singleton.

priority = 15.1: The type of the None singleton.

class AutoSummExceptionDocumenter(*args: Any)[source]

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`	The type of the None singleton.
`option_spec`	The type of the None singleton.
`priority`	The type of the None singleton.

add_content(*args, **kwargs)[source]: Add content from docstrings, attribute documentation and user.

member_sections: dict = {10: 'Classes', 50: 'Methods', 60: 'Attributes'}: The type of the None singleton.

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>, 'no-index-entry': <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>}: The type of the None singleton.

priority = 20.1: The type of the None singleton.

class AutoSummModuleDocumenter(*args: Any)[source]

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`	The type of the None singleton.
`option_spec`	The type of the None singleton.
`priority`	The type of the None singleton.

add_content(*args, **kwargs)[source]: Add content from docstrings, attribute documentation and user.

member_sections: dict = {10: 'Exceptions', 20: 'Classes', 30: 'Functions', 40: 'Data'}: The type of the None singleton.

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-index-entry': <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>}: The type of the None singleton.

priority = 0.1: The type of the None singleton.

class AutosummaryDocumenter[source]

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`	The type of the None singleton.
`grouper_funcs`	The type of the None singleton.

add_autosummary(relative_ref_paths=False)[source]

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 = []: The type of the None singleton.

get_grouped_documenters(all_members=False)[source]

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 = []: The type of the None singleton.

class CallableAttributeDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]

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

The type of the None singleton.

format_args()[source]

Format the argument signature of self.object.

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

get_doc(*args, **kwargs)[source]: Reimplemented to include data from the call method

priority = 10.1: The type of the None singleton.

class CallableDataDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]

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

The type of the None singleton.

format_args()[source]

Format the argument signature of self.object.

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

get_doc(*args, **kwargs)[source]: Reimplemented to include data from the call method

priority = -9.9: The type of the None singleton.

class NoDataAttributeDocumenter(*args, **kwargs)[source]

Bases: CallableAttributeDocumenter

AttributeDocumenter that prevents the displaying of large data

Attributes:

priority

The type of the None singleton.

priority = 10.2: The type of the None singleton.

class NoDataDataDocumenter(*args, **kwargs)[source]

Bases: CallableDataDocumenter

DataDocumenter that prevents the displaying of large data

Attributes:

priority

The type of the None singleton.

priority = -9.8: The type of the None singleton.

dont_document_data(config, fullname)[source]

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)[source]: 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'}: The type of the None singleton.

setup(app)[source]: setup function for using this module as a sphinx extension