`more_autodoc.variables`¶

Documenter for module level variables, similar to autodata but with a different appearance and more customisation options.

New in version 0.6.0.

Enable sphinx_toolbox.more_autodoc.variables by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.more_autodoc.variables',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Changed in version 0.7.0: Added *AttributeDocumenters

Changed in version 1.1.0: Added SlotsAttributeDocumenter

Usage¶

.. autovariable::¶

Directive to automatically document a variable.

The output is based on the autodata directive, and takes all of its options, plus these additional ones:

:no-value:¶: Don’t show the value of the variable.

:value: value (string)¶: Show this instead of the value taken from the Python source code.

:no-type:¶: Don’t show the type of the variable.

:type: type (string)¶: Show this instead of the type taken from the Python source code.

An example of the output cen be seen below for type_template.

API Reference¶

Classes:

`VariableDocumenter`(directive, name[, indent])	Specialized Documenter subclass for data items.
`TypedAttributeDocumenter`(directive, name[, …])	Alternative version of `sphinx.ext.autodoc.AttributeDocumenter` with better type hint rendering.
`InstanceAttributeDocumenter`(directive, name)	Alternative version of `sphinx.ext.autodoc.InstanceAttributeDocumenter` with better type hint rendering.
`SlotsAttributeDocumenter`(directive, name[, …])	Alternative version of `sphinx.ext.autodoc.InstanceAttributeDocumenter` with better type hint rendering.

Data:

type_template

Template for rendering type annotations in VariableDocumenter, TypedAttributeDocumenter and InstanceAttributeDocumenter.

Functions:

`get_variable_type`(documenter)	Returns the formatted type annotation for a variable.
`setup`(app)	Setup `sphinx_toolbox.more_autodoc.variables`.

class VariableDocumenter(directive, name, indent='')[source]¶

Bases: DataDocumenter

Specialized Documenter subclass for data items.

Methods:

add_directive_header(sig)

Add the directive’s header.

add_directive_header(sig)[source]¶

Add the directive’s header.

Parameters: sig (str)

class TypedAttributeDocumenter(directive, name, indent='')[source]¶

Bases: DocstringStripSignatureMixin, ClassLevelDocumenter

Alternative version of sphinx.ext.autodoc.AttributeDocumenter with better type hint rendering.

Specialized Documenter subclass for attributes.

New in version 0.7.0.

Changed in version 1.0.0: Now uses the type of the variable if it is not explicitly annotated.

Methods:

`can_document_member`(member, membername, …)	Called to see if a member can be documented by this documenter.
`add_directive_header`(sig)	Add the directive’s header.
`get_doc`([encoding, ignore])	Decode and return lines of the docstring(s) for the object.
`add_content`(more_content[, no_docstring])	Add content from docstrings, attribute documentation and user.

classmethod can_document_member(member, membername, isattr, parent)[source]¶

Called to see if a member can be documented by this documenter.

Return type: bool

add_directive_header(sig)[source]¶

Add the directive’s header.

Parameters: sig (str)

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

Decode and return lines of the docstring(s) for the object.

Parameters

encoding (Optional[str]) – Default None.
ignore (Optional[int]) – Default None.

Return type

List[List[str]]

add_content(more_content, no_docstring=False)[source]¶: Add content from docstrings, attribute documentation and user.

class InstanceAttributeDocumenter(directive, name, indent='')[source]¶

Bases: TypedAttributeDocumenter

Alternative version of sphinx.ext.autodoc.InstanceAttributeDocumenter with better type hint rendering.

Specialized Documenter subclass for attributes that cannot be imported because they are instance attributes (e.g. assigned in __init__).

New in version 0.7.0.

Changed in version 1.0.0: Now uses the type of the variable if it is not explicitly annotated.

Methods:

`can_document_member`(member, membername, …)	Called to see if a member can be documented by this documenter.
`import_parent`()	Import and return the attribute’s parent.
`add_content`(more_content[, no_docstring])	Never try to get a docstring from the object.

classmethod can_document_member(member, membername, isattr, parent)[source]¶

Called to see if a member can be documented by this documenter.

This documenter only documents INSTANCEATTR members.

Parameters

member (Any) – The member being checked.
membername (str) – The name of the member.
isattr (bool)
parent (Any) – The parent of the member.

Return type

bool

import_parent()[source]¶

Import and return the attribute’s parent.

Return type: Any

add_content(more_content, no_docstring=False)[source]¶: Never try to get a docstring from the object.

class SlotsAttributeDocumenter(directive, name, indent='')[source]¶

Bases: TypedAttributeDocumenter

Alternative version of sphinx.ext.autodoc.InstanceAttributeDocumenter with better type hint rendering.

Specialized Documenter subclass for attributes that cannot be imported because they are attributes in __slots__.

New in version 1.1.0.

Methods:

`can_document_member`(member, membername, …)	Called to see if a member can be documented by this documenter.
`get_doc`([encoding, ignore])	Decode and return lines of the docstring(s) for the object.

classmethod can_document_member(member, membername, isattr, parent)[source]¶

Called to see if a member can be documented by this documenter.

This documenter only documents SLOTSATTR members.

Parameters

member (Any) – The member being checked.
membername (str) – The name of the member.
isattr (bool)
parent (Any) – The parent of the member.

Return type

bool

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

Decode and return lines of the docstring(s) for the object.

Parameters

encoding (Optional[str]) – Default None.
ignore (Optional[int]) – Default None.

Return type

List[List[str]]

Type: str

Template for rendering type annotations in VariableDocumenter, TypedAttributeDocumenter and InstanceAttributeDocumenter.

Renders like:

Type: str

get_variable_type(documenter)[source]¶

Returns the formatted type annotation for a variable.

Parameters: documenter (Documenter)
Return type: str

setup(app)[source]¶

Setup sphinx_toolbox.more_autodoc.variables.

Parameters: app (Sphinx) – The Sphinx application.
Return type: SphinxExtMetadata

more_autodoc.variables¶

Usage¶

API Reference¶

`more_autodoc.variables`¶