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 autodoc.AttributeDocumenter with better type hint rendering.

InstanceAttributeDocumenter(directive, name)

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

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.

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 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
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 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 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
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.

old_type_template = '   **Type:** |nbsp| |nbsp| |nbsp| |nbsp| %s'

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