sphinx.ext.autodoc

package documentation

Automatically insert docstrings for functions, classes or whole modules into the doctree, thus avoiding duplication between docstrings and documentation for those who like elaborate docstrings.

Unknown Field: copyright
Copyright 2007-2022 by the Sphinx team, see AUTHORS.
Unknown Field: license
BSD, see LICENSE for details.

Module	`deprecated`	sphinx.ext.autodoc.deprecated ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Module	`directive`	sphinx.ext.autodoc.directive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Module	`importer`	sphinx.ext.autodoc.importer ~~~~~~~~~~~~~~~~~~~~~~~~~~~
Module	`mock`	sphinx.ext.autodoc.mock ~~~~~~~~~~~~~~~~~~~~~~~
Module	`preserve_defaults`	sphinx.ext.autodoc.preserve_defaults ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Module	`type_comment`	sphinx.ext.autodoc.type_comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Module	`typehints`	sphinx.ext.autodoc.typehints ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

From __init__.py:

Function	`between`	No summary
Function	`cut_lines`	Return a listener that removes the first pre and last post lines of every docstring. If what is a sequence of strings, only docstrings of a type in what will be processed.
Constant	`ALL`	Undocumented
Constant	`EMPTY`	Undocumented
Constant	`INSTANCEATTR`	Undocumented
Constant	`SLOTSATTR`	Undocumented
Constant	`SUPPRESS`	Undocumented
Constant	`UNINITIALIZED_ATTR`	Undocumented
Variable	`logger`	Undocumented
Variable	`MethodDescriptorType`	Undocumented
Variable	`ObjectMembers`	Undocumented
Variable	`py_ext_sig_re`	Undocumented
Variable	`special_member_re`	Undocumented
Class	`_All`	A special value for :*-members: that matches to any member.
Class	`_Empty`	A special value for :exclude-members: that never matches to any member.
Class	`AttributeDocumenter`	Specialized Documenter subclass for attributes.
Class	`ClassDocumenter`	Specialized Documenter subclass for classes.
Class	`ClassLevelDocumenter`	Specialized Documenter subclass for objects on class level (methods, attributes).
Class	`DataDocumenter`	Specialized Documenter subclass for data items.
Class	`DataDocumenterMixinBase`	No class docstring; 0/6 class variable, 3/3 methods documented
Class	`DecoratorDocumenter`	Specialized Documenter subclass for decorator functions.
Class	`DocstringSignatureMixin`	Mixin for FunctionDocumenter and MethodDocumenter to provide the feature of reading the signature from the docstring.
Class	`DocstringStripSignatureMixin`	Mixin for AttributeDocumenter to provide the feature of stripping any function signature from the docstring.
Class	`Documenter`	A Documenter knows how to autodocument a single object type. When registered with the AutoDirective, it will be used to document objects of that type when needed by autodoc.
Class	`ExceptionDocumenter`	Specialized ClassDocumenter subclass for exceptions.
Class	`FunctionDocumenter`	Specialized Documenter subclass for functions.
Class	`GenericAliasMixin`	Mixin for DataDocumenter and AttributeDocumenter to provide the feature for supporting GenericAliases.
Class	`MethodDocumenter`	Specialized Documenter subclass for methods (normal, static and class).
Class	`ModuleDocumenter`	Specialized Documenter subclass for modules.
Class	`ModuleLevelDocumenter`	Specialized Documenter subclass for objects on module level (functions, classes, data/constants).
Class	`NewTypeAttributeDocumenter`	Specialized Documenter subclass for NewTypes.
Class	`NewTypeDataDocumenter`	Specialized Documenter subclass for NewTypes.
Class	`NewTypeMixin`	Mixin for DataDocumenter and AttributeDocumenter to provide the feature for supporting NewTypes.
Class	`NonDataDescriptorMixin`	Mixin for AttributeDocumenter to provide the feature for supporting non data-descriptors.
Class	`ObjectMember`	A member of object.
Class	`Options`	A dict/attribute hybrid that returns None on nonexisting keys.
Class	`PropertyDocumenter`	Specialized Documenter subclass for properties.
Class	`RuntimeInstanceAttributeMixin`	Mixin for AttributeDocumenter to provide the feature for supporting runtime instance attributes (that are defined in __init__() methods with doc-comments).
Class	`SlotsMixin`	Mixin for AttributeDocumenter to provide the feature for supporting __slots__.
Class	`TypeVarMixin`	Mixin for DataDocumenter and AttributeDocumenter to provide the feature for supporting TypeVars.
Class	`UninitializedGlobalVariableMixin`	Mixin for DataDocumenter to provide the feature for supporting uninitialized (type annotation only) global variables.
Class	`UninitializedInstanceAttributeMixin`	Mixin for AttributeDocumenter to provide the feature for supporting uninitialized instance attributes (PEP-526 styled, annotation only attributes).
Function	`annotation_option`	Undocumented
Function	`autodoc_attrgetter`	Alternative getattr() for types
Function	`bool_option`	Used to convert flag options to auto directives. (Instead of directives.flag(), which returns None).
Function	`class_doc_from_option`	Used to convert the :class-doc-from: option to autoclass directives.
Function	`exclude_members_option`	Used to convert the :exclude-members: option.
Function	`get_documenters`	Returns registered Documenter classes
Function	`identity`	Undocumented
Function	`inherited_members_option`	Used to convert the :members: option to auto directives.
Function	`member_order_option`	Used to convert the :members: option to auto directives.
Function	`members_option`	Used to convert the :members: option to auto directives.
Function	`members_set_option`	Used to convert the :members: option to auto directives.
Function	`merge_members_option`	Merge :*-members: option to the :members: option.
Function	`merge_special_members_option`	Merge :special-members: option to :members: option.
Function	`migrate_autodoc_member_order`	Undocumented
Function	`setup`	Undocumented
Constant	`_CLASS_NEW_BLACKLIST`	Undocumented
Constant	`_METACLASS_CALL_BLACKLIST`	Undocumented

logger =

Undocumented

MethodDescriptorType =

Undocumented

py_ext_sig_re =

Undocumented

special_member_re =

Undocumented

def identity(x):

Undocumented

Parameters
x:`Any`	Undocumented
Returns
`Any`	Undocumented

ALL =

Undocumented

Value

_All()

EMPTY =

Undocumented

Value

_Empty()

UNINITIALIZED_ATTR =

Undocumented

Value

object()

INSTANCEATTR =

Undocumented

Value

object()

SLOTSATTR =

Undocumented

Value

object()

def members_option(arg):

Used to convert the :members: option to auto directives.

Parameters
arg:`Any`	Undocumented
Returns
`Union[object, List[str]]`	Undocumented

def members_set_option(arg):

Used to convert the :members: option to auto directives.

Parameters
arg:`Any`	Undocumented
Returns
`Union[object, Set[str]]`	Undocumented

def exclude_members_option(arg):

Used to convert the :exclude-members: option.

Parameters
arg:`Any`	Undocumented
Returns
`Union[object, Set[str]]`	Undocumented

def inherited_members_option(arg):

Used to convert the :members: option to auto directives.

Parameters
arg:`Any`	Undocumented
Returns
`Union[object, Set[str]]`	Undocumented

def member_order_option(arg):

Used to convert the :members: option to auto directives.

Parameters
arg:`Any`	Undocumented
Returns
`Optional[str]`	Undocumented

def class_doc_from_option(arg):

Used to convert the :class-doc-from: option to autoclass directives.

Parameters
arg:`Any`	Undocumented
Returns
`Optional[str]`	Undocumented

SUPPRESS =

Undocumented

Value

object()

def annotation_option(arg):

Undocumented

Parameters
arg:`Any`	Undocumented
Returns
`Any`	Undocumented

def bool_option(arg):

Used to convert flag options to auto directives. (Instead of directives.flag(), which returns None).

Parameters
arg:`Any`	Undocumented
Returns
`bool`	Undocumented

def merge_special_members_option(options):

Merge :special-members: option to :members: option.

Parameters
options:`Dict`	Undocumented

def merge_members_option(options):

Merge :*-members: option to the :members: option.

Parameters
options:`Dict`	Undocumented

def cut_lines(pre, post=0, what=None):

Return a listener that removes the first pre and last post lines of every docstring. If what is a sequence of strings, only docstrings of a type in what will be processed.

Use like this (e.g. in the setup() function of :file:`conf.py`):

from sphinx.ext.autodoc import cut_lines
app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))

This can (and should) be used in place of :confval:`automodule_skip_lines`.

Parameters
pre:`int`	Undocumented
post:`int`	Undocumented
what:`str`	Undocumented
Returns
`Callable`	Undocumented

def between(marker, what=None, keepempty=False, exclude=False):

Return a listener that either keeps, or if exclude is True excludes, lines between lines that match the marker regular expression. If no line matches, the resulting docstring would be empty, so no change will be made unless keepempty is true.

If what is a sequence of strings, only docstrings of a type in what will be processed.

Parameters
marker:`str`	Undocumented
what:`Sequence[str]`	Undocumented
keepempty:`bool`	Undocumented
exclude:`bool`	Undocumented
Returns
`Callable`	Undocumented

ObjectMembers =

Undocumented

_METACLASS_CALL_BLACKLIST: list[str] =

Undocumented

Value

['enum.EnumMeta.__call__']

_CLASS_NEW_BLACKLIST: list[str] =

Undocumented

Value

['typing.Generic.__new__']

def get_documenters(app):

Returns registered Documenter classes

Parameters
app:`Sphinx`	Undocumented
Returns
`Dict[str, Type[Documenter]]`	Undocumented

def autodoc_attrgetter(app, obj, name, *defargs):

Alternative getattr() for types

Parameters
app:`Sphinx`	Undocumented
obj:`Any`	Undocumented
name:`str`	Undocumented
*defargs:`Any`	Undocumented
Returns
`Any`	Undocumented

def migrate_autodoc_member_order(app, config):

Undocumented

Parameters
app:`Sphinx`	Undocumented
config:`Config`	Undocumented

def setup(app):

Undocumented

Parameters
app:`Sphinx`	Undocumented
Returns
`Dict[str, Any]`	Undocumented