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

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

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

Bases: sphinx.util.docutils.SphinxDirective

A directive to generate an autosummary.

Usage:

.. autoclasssum:: <Class>

.. automodsum:: <module>

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

class AutoSummClassDocumenter(*args: Any)[source]

Bases: sphinx.ext.autodoc.ClassDocumenter, autodocsumm.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

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

Add content from docstrings, attribute documentation and user.

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

OrderedDict 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: Dict[str, Callable[[str], Any]] = {'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>, '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 = 0.1

slightly higher priority than sphinx.ext.autodoc.ClassDocumenter

class AutoSummModuleDocumenter(*args: Any)[source]

Bases: sphinx.ext.autodoc.ModuleDocumenter, autodocsumm.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

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

Add content from docstrings, attribute documentation and user.

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

OrderedDict 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: Dict[str, Callable[[str], Any]] = {'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>, '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[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()

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

Add the autosammary table of this documenter.

filter_funcs = []

List of functions that may filter the members

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 = []

Grouper functions

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

Bases: sphinx.ext.autodoc.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

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

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

Bases: sphinx.ext.autodoc.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

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

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

Bases: autodocsumm.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)[source]

Bases: autodocsumm.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)[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'}

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

setup(app)[source]

setup function for using this module as a sphinx extension