API Reference

Sphinx extension that defines a new automodule directive with autosummary

The AutoSummDirective defined in this extension module allows the same functionality as the automodule and autoclass directives of the sphinx.ext.autodoc module but with an additional autosummary option. This option puts a autosummary in the style of the sphinx.ext.autosummary module at the beginning of the class or module. The content of this autosummary is automatically determined by the results of the automodule (or autoclass) directive.

This extension gives also the possibility to choose which data shall be shown and to include the docstring of the '__call__' attribute.

Classes

AutoSummClassDocumenter(*args) Class documentor suitable for the AutoSummDirective
AutoSummDirective(name, arguments, options, …) automodule directive that makes a summary at the beginning of the module
AutoSummModuleDocumenter(*args) Module documentor suitable for the AutoSummDirective
AutosummaryDocumenter() Abstract class for for extending Documenter methods
CallableAttributeDocumenter(directive, name) sphinx.ext.autodoc.AttributeDocumenter that uses the __call__
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
process_signature(obj)
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
class AutoSummClassDocumenter(*args)[source]

Bases: sphinx.ext.autodoc.ClassDocumenter, autodocsumm.AutosummaryDocumenter

Class documentor suitable for the AutoSummDirective

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 at the beginning. It’s priority is slightly higher than the one of the ClassDocumenter

Attributes

member_sections OrderedDict that includes the autosummary sections
option_spec original option_spec from sphinx.ext.autodoc.ClassDocumenter
priority slightly higher priority than
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 = {'autosummary': <function bool_option>, 'autosummary-exclude-members': <function members_set_option>, 'autosummary-inherited-members': <function bool_option>, 'autosummary-members': <function members_option>, 'autosummary-no-nesting': <function bool_option>, 'autosummary-private-members': <function bool_option>, 'autosummary-special-members': <function members_option>, 'autosummary-undoc-members': <function bool_option>, 'exclude-members': <function members_set_option>, 'inherited-members': <function bool_option>, 'member-order': <function identity>, 'members': <function members_option>, 'noindex': <function bool_option>, 'private-members': <function bool_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 AutoSummDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: sphinx.ext.autodoc.directive.AutodocDirective, sphinx.ext.autosummary.Autosummary

automodule directive that makes a summary at the beginning of the module

This directive combines the sphinx.ext.autodoc.directives.AutodocDirective and sphinx.ext.autosummary.Autosummary directives to put a summary of the specified module at the beginning of the module documentation.

Methods

autosumm_nodes(documenter, …) Create the autosummary nodes based on the documenter content
get_items_from_documenters(documenters) Return the items needed for creating the tables
inject_summ_nodes(doc_nodes, summ_nodes) Method to inject the autosummary nodes into the autodoc nodes
run() Run method for the directive

Attributes

autosummary_documenter Returns the AutosummaryDocumenter subclass that can be used
autosumm_nodes(documenter, grouped_documenters, nested)[source]

Create the autosummary nodes based on the documenter content

Parameters:
  • documenter (sphinx.ext.autodoc.Documenter) – The base (module or class) documenter for which to generate the autosummary tables of its members
  • grouped_documenters (dict) – The dictionary as it is returned from the AutosummaryDocumenter.get_grouped_documenters() method
  • nested (bool) – If true, autosummary tables will also be created for members.
Returns:

a mapping from the objects fullname to the corresponding autosummary tables of its members. The objects include the main object of the given documenter and the classes that are defined in it

Return type:

dict

autosummary_documenter

Returns the AutosummaryDocumenter subclass that can be used

get_items_from_documenters(documenters)[source]

Return the items needed for creating the tables

This method creates the items that are used by the sphinx.ext.autosummary.Autosummary.get_table() method by what is taken from the values of the AutoSummModuleDocumenter.get_grouped_documenters() method.

Returns:A list containing tuples like (name, signature, summary_string, real_name) that can be used for the sphinx.ext.autosummary.Autosummary.get_table() method.
Return type:list
inject_summ_nodes(doc_nodes, summ_nodes)[source]

Method to inject the autosummary nodes into the autodoc nodes

Parameters:
  • doc_nodes (list) – The list of nodes as they are generated by the sphinx.ext.autodoc.AutodocDirective.run() method
  • summ_nodes (dict) – The generated autosummary nodes as they are generated by the autosumm_nodes() method. Note that summ_nodes must only contain the members autosummary tables!
Returns:

doc_nodes – The modified doc_nodes

Return type:

list

Notes

doc_nodes are modified in place and not copied!

run()[source]

Run method for the directive

class AutoSummModuleDocumenter(*args)[source]

Bases: sphinx.ext.autodoc.ModuleDocumenter, autodocsumm.AutosummaryDocumenter

Module documentor suitable for the AutoSummDirective

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

Attributes

member_sections OrderedDict that includes the autosummary sections
option_spec original option_spec from sphinx.ext.autodoc.ModuleDocumenter
priority slightly higher priority than
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 = {'autosummary': <function bool_option>, 'autosummary-exclude-members': <function members_set_option>, 'autosummary-ignore-module-all': <function bool_option>, 'autosummary-imported-members': <function bool_option>, 'autosummary-inherited-members': <function bool_option>, 'autosummary-members': <function members_option>, 'autosummary-no-nesting': <function bool_option>, 'autosummary-private-members': <function bool_option>, 'autosummary-special-members': <function members_option>, 'autosummary-undoc-members': <function bool_option>, 'deprecated': <function bool_option>, 'exclude-members': <function members_set_option>, 'ignore-module-all': <function bool_option>, 'imported-members': <function bool_option>, 'inherited-members': <function bool_option>, 'member-order': <function identity>, 'members': <function members_option>, 'noindex': <function bool_option>, 'platform': <function identity>, 'private-members': <function bool_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 the AutoSummDirective.

Attributes

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

Methods

get_grouped_documenters([all_members]) Method to return the member documenters
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. The dictionary can be used in the AutoSummDirective.get_items_from_documenters() method
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, name, indent=u'')[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([encoding, ignore]) Reimplemented to include data from the call method

Attributes

priority float(x) -> floating point number
format_args()[source]

Format the argument signature of self.object.

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

get_doc(encoding=None, ignore=1)[source]

Reimplemented to include data from the call method

priority = 10.1
class CallableDataDocumenter(directive, name, indent=u'')[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([encoding, ignore]) Reimplemented to include data from the call method

Attributes

priority float(x) -> floating point number
format_args()[source]

Format the argument signature of self.object.

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

get_doc(encoding=None, ignore=1)[source]

Reimplemented to include data from the call method

priority = -9.9
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

member_options = set(['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

process_signature(obj)[source]
setup(app)[source]

setup function for using this module as a sphinx extension