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:
|
A directive to generate an autosummary. |
|
Class documentor with autosummary tables for its members. |
|
Module documentor with autosummary tables of its members. |
Abstract class for for extending Documenter methods |
|
|
|
|
|
|
AttributeDocumenter that prevents the displaying of large data |
|
DataDocumenter that prevents the displaying of large data |
Functions:
|
Check whether the given object should be documented |
|
Transform a string to a list by splitting at ;;. |
|
setup function for using this module as a sphinx extension |
Data:
Options of the |
- class AutoDocSummDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]
Bases:
SphinxDirective
A directive to generate an autosummary.
Usage:
.. autoclasssum:: <Class> .. automodsum:: <module>
The directive additionally supports all options of the
autoclass
orautomod
directive respectively. Sections can be a list of section titles to be included. If ommitted, all sections are used.Attributes:
May the directive have content?
Mapping of option names to validator functions.
Number of optional arguments after the required arguments.
Number of required directive arguments.
- 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)[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 ClassDocumenterMethods:
add_content
(*args, **kwargs)Add content from docstrings, attribute documentation and user.
Attributes:
dict
that includes the autosummary sectionsoriginal option_spec from
sphinx.ext.autodoc.ClassDocumenter
but with additional autosummary boolean optionslightly 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'}
dict
that includes the autosummary sectionsThis 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: 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 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:
dict
that includes the autosummary sectionsoriginal option_spec from
sphinx.ext.autodoc.ModuleDocumenter
but with additional autosummary boolean optionslightly 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'}
dict
that includes the autosummary sectionsThis 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: 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[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:
List of functions that may filter the members
Grouper functions
- 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 = []
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 thesphinx.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:
Notes
If a
sphinx.ext.autodoc.Documenter.member_order
value is not in themember_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:
AttributeDocumenter
sphinx.ext.autodoc.AttributeDocumenter
that uses the __call__ attrMethods:
Format the argument signature of self.object.
get_doc
(*args, **kwargs)Reimplemented to include data from the call method
Attributes:
priority if multiple documenters return True from can_document_member
- format_args()[source]
Format the argument signature of self.object.
Should return None if the object does not have a signature.
- priority = 10.1
priority if multiple documenters return True from can_document_member
- class CallableDataDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]
Bases:
DataDocumenter
sphinx.ext.autodoc.DataDocumenter
that uses the __call__ attrMethods:
Format the argument signature of self.object.
get_doc
(*args, **kwargs)Reimplemented to include data from the call method
Attributes:
priority if multiple documenters return True from can_document_member
- format_args()[source]
Format the argument signature of self.object.
Should return None if the object does not have a signature.
- priority = -9.9
priority if multiple documenters return True from can_document_member
- class NoDataAttributeDocumenter(*args, **kwargs)[source]
Bases:
CallableAttributeDocumenter
AttributeDocumenter that prevents the displaying of large data
Attributes:
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:
CallableDataDocumenter
DataDocumenter that prevents the displaying of large data
Attributes:
slightly higher priority as the one of the CallableDataDocumenter
- priority = -9.8
slightly higher priority as the one of the CallableDataDocumenter
- 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