`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

Changed in version 3.7.0: Added PropertyDocumenter

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 `autodoc.AttributeDocumenter` with better type hint rendering.
`InstanceAttributeDocumenter`(directive, name)	Alternative version of `autodoc.InstanceAttributeDocumenter` with better type hint rendering.
`PropertyDocumenter`(directive, name[, indent])	Specialized Documenter subclass for properties.
`SlotsAttributeDocumenter`(directive, name[, ...])	Alternative version of `autodoc.InstanceAttributeDocumenter` with better type hint rendering.

Data:

`type_template`	Template for rendering type annotations in `VariableDocumenter`, `TypedAttributeDocumenter` and `InstanceAttributeDocumenter`.
`old_type_template`	Old 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 and options to the generated content.

objtype = 'variable'¶: Type: str

priority = -9.5¶: Type: float

add_directive_header(sig)[source]¶

Add the directive’s header and options to the generated content.

Parameters:: sig (str) – The function/class signature.

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

Bases: DocstringStripSignatureMixin, ClassLevelDocumenter

Alternative version of 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 and options to the generated content.
`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.

objtype = 'attribute'¶: Type: str

member_order = 60¶: Type: int

priority = 10¶: Type: int

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

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

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

add_directive_header(sig)[source]¶

Add the directive’s header and options to the generated content.

Parameters:: sig (str) – The function/class signature.

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.

Parameters:

more_content (Optional[StringList])
no_docstring (bool) – Default False.

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

Bases: TypedAttributeDocumenter

Alternative version of 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.

objtype = 'instanceattribute'¶: Type: str

member_order = 60¶: Type: int

priority = 11¶: Type: int

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 PropertyDocumenter(directive, name, indent='')[source]¶

Bases: TypedAttributeDocumenter

Specialized Documenter subclass for properties.

New in version 3.7.0.

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 and options to the generated content.

objtype = 'property'¶: Type: str

member_order = 60¶: Type: int

priority = 11¶: Type: int

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

add_directive_header(sig)[source]¶

Add the directive’s header and options to the generated content.

Parameters:: sig (str) – The function/class signature.

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

Bases: TypedAttributeDocumenter

Alternative version of 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.

objtype = 'slotsattribute'¶: Type: str

member_order = 60¶: Type: int

priority = 11¶: Type: int

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_template = ' **Type:**\xa0\xa0\xa0\xa0%s'¶

Type: str

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

Renders like:

Type: str

Changed in version 3.4.0: This template now uses the unicode codepoint for a non-breaking space, rather than the ReStructuredText substitution used in 3.3.0 and earlier. The old template is available as old_type_template.

Type: str

Old template for rendering type annotations in VariableDocumenter, TypedAttributeDocumenter and InstanceAttributeDocumenter.

Renders like:

Type: str

Note

Be sure to call :func:~.add_nbsp_substitution` in the setup function of any extensions using this template.

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`¶