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 *AttributeDocumenter
s
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:
|
Specialized Documenter subclass for data items. |
|
Alternative version of |
|
Alternative version of |
|
Alternative version of |
Data:
Template for rendering type annotations in |
Functions:
|
Returns the formatted type annotation for a variable. |
|
-
class
VariableDocumenter
(directive, name, indent='')[source]¶ Bases:
DataDocumenter
Specialized Documenter subclass for data items.
Methods:
add_directive_header
(sig)Add the directive’s header.
-
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
-
classmethod
-
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 and return the attribute’s parent.
add_content
(more_content[, no_docstring])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.
-
type_template
= ' **Type:** |nbsp| |nbsp| |nbsp| |nbsp| %s'¶ Type:
str
Template for rendering type annotations in
VariableDocumenter
,TypedAttributeDocumenter
andInstanceAttributeDocumenter
.Renders like:
Type:
str
-
get_variable_type
(documenter)[source]¶ Returns the formatted type annotation for a variable.
- Parameters
documenter (
Documenter
)- Return type
-
setup
(app)[source]¶ Setup
sphinx_toolbox.more_autodoc.variables
.- Parameters
app (
Sphinx
) – The Sphinx application.- Return type