Templates¶
A lot of the power from AutoAPI comes from templates. We are basically building a mapping from code to docs, and templates let you highly customise the display of said docs.
Structure¶
Every type of data structure has its own template.
It uses the form python/type.rst
to find the template to render.
The full search path is:
python/type.rst
So for a Python Class, this would resolve to:
python/class.rst
We provide base/base.rst
as an incredibly basic output of every object:
.. py:{type}:: {name}
Custom Filters, Tests, and Globals¶
The autoapi_prepare_jinja_env
configuration option allows you
to pass a callback that can edit the jinja2.Environment
object
before rendering begins.
This callback, among other things, can be used to add custom filters,
tests, and/or globals to the Jinja environment. For example:
def autoapi_prepare_jinja_env(jinja_env):
jinja_env.filters["my_custom_filter"] = lambda value: value.upper()
Context¶
Every template is given a set context that can be accessed in the templates. This contains:
autoapi_options
: The value of theautoapi_options
configuration option.include_summaries
: The value of theautoapi_include_summaries
configuration option.obj
: A Python object derived fromPythonPythonMapper
.sphinx_version
: The contents ofsphinx.version_info
.
The object in obj
has a number of standard attributes
that you can reliably access.
Warning
These classes should not be constructed manually.
They can be reliably accessed through templates
and autoapi-skip-member
only.
- class autoapi.mappers.python.objects.PythonPythonMapper(obj, class_content='class', **kwargs)¶
A base class for all types of representations of Python objects.
- name¶
The name given to this object.
- Type:
str
- id¶
A unique identifier for this object.
- Type:
str
- children¶
The members of this object.
- Type:
list(PythonPythonMapper)
- property display¶
Whether this object should be displayed in documentation.
This attribute depends on the configuration options given in
autoapi_options
and the result ofautoapi-skip-member
.- Type:
bool
- property docstring¶
The docstring for this object.
If a docstring did not exist on the object, this will be the empty string.
For classes this will also depend on the
autoapi_python_class_content
option.- Type:
str
- inherited¶
Whether this was inherited from an ancestor of the parent class.
- Type:
bool
- is_callable = False¶
- property is_private_member¶
Whether this object is private (True) or not (False).
- Type:
bool
- property is_special_member¶
Whether this object is a special member (True) or not (False).
- Type:
bool
- property is_undoc_member¶
Whether this object has a docstring (False) or not (True).
- Type:
bool
- language = python¶
- member_order = 0¶
- class autoapi.mappers.python.objects.PythonFunction(obj, **kwargs)¶
Bases:
PythonPythonMapper
The representation of a function.
- args¶
The arguments to this object, formatted as a string.
- Type:
str
- is_callable = True¶
- member_order = 30¶
- overloads¶
The overloaded signatures of this function.
Each tuple is a tuple of
(args, return_annotation)
- Type:
list(tuple(str, str))
- properties¶
The properties that describe what type of function this is.
Can be only be: async
- Type:
list(str)
- return_annotation¶
The type annotation for the return type of this function.
This will be
None
if an annotation or annotation comment was not given.- Type:
str or None
- type = function¶
- class autoapi.mappers.python.objects.PythonMethod(obj, **kwargs)¶
Bases:
PythonFunction
The representation of a method.
- is_callable = True¶
- member_order = 50¶
- properties¶
The properties that describe what type of method this is.
Can be any of: abstractmethod, async, classmethod, property, staticmethod
- Type:
list(str)
- type = method¶
- class autoapi.mappers.python.objects.PythonProperty(obj, **kwargs)¶
Bases:
PythonPythonMapper
The representation of a property on a class.
- annotation¶
The type annotation of this property.
- Type:
str or None
- member_order = 60¶
- properties¶
The properties that describe what type of property this is.
Can be any of: abstractmethod, classmethod
- Type:
list(str)
- type = property¶
- class autoapi.mappers.python.objects.PythonData(obj, **kwargs)¶
Bases:
PythonPythonMapper
Global, module level data.
- annotation¶
The type annotation of this attribute.
This will be
None
if an annotation or annotation comment was not given.- Type:
str or None
- member_order = 40¶
- type = data¶
- value¶
The value of this attribute.
This will be
None
if the value is not constant.- Type:
str or None
- class autoapi.mappers.python.objects.PythonAttribute(obj, **kwargs)¶
Bases:
PythonData
An object/class level attribute.
- member_order = 60¶
- type = attribute¶
- class autoapi.mappers.python.objects.TopLevelPythonPythonMapper(obj, **kwargs)¶
Bases:
PythonPythonMapper
A common base class for modules and packages.
- all¶
The contents of
__all__
if assigned to.Only constants are included. This will be
None
if no__all__
was set.- Type:
list(str) or None
- property classes¶
All of the member classes.
- Type:
list(PythonClass)
- property functions¶
All of the member functions.
- Type:
list(PythonFunction)
- top_level_object¶
Whether this object is at the very top level (True) or not (False).
This will be False for subpackages and submodules.
- Type:
bool
- class autoapi.mappers.python.objects.PythonModule(obj, **kwargs)¶
Bases:
TopLevelPythonPythonMapper
The representation of a module.
- type = module¶
- class autoapi.mappers.python.objects.PythonPackage(obj, **kwargs)¶
Bases:
TopLevelPythonPythonMapper
The representation of a package.
- type = package¶
- class autoapi.mappers.python.objects.PythonClass(obj, **kwargs)¶
Bases:
PythonPythonMapper
The representation of a class.
- property args¶
The arguments to this object, formatted as a string.
- Type:
str
- property attributes¶
- bases¶
The fully qualified names of all base classes.
- Type:
list(str)
- property classes¶
- property constructor¶
- property constructor_docstring¶
- property docstring¶
The docstring for this object.
If a docstring did not exist on the object, this will be the empty string.
For classes this will also depend on the
autoapi_python_class_content
option.- Type:
str
- member_order = 20¶
- property methods¶
- property overloads¶
- property properties¶
- type = class¶
- class autoapi.mappers.python.objects.PythonException(obj, **kwargs)¶
Bases:
PythonClass
The representation of an exception class.
- member_order = 10¶
- type = exception¶