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.
- children#
The members of this object.
- Type:
- 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:
- 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:
- is_callable = False#
- property is_special_member#
Whether this object is a special member (True) or not (False).
- Type:
- language = python#
- member_order = 0#
- class autoapi.mappers.python.objects.PythonFunction(obj, **kwargs)#
Bases:
PythonPythonMapper
The representation of a function.
- is_callable = True#
- member_order = 30#
- overloads#
The overloaded signatures of this function.
Each tuple is a tuple of
(args, return_annotation)
- properties#
The properties that describe what type of function this is.
Can be only be: async
- 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 = method#
- class autoapi.mappers.python.objects.PythonProperty(obj, **kwargs)#
Bases:
PythonPythonMapper
The representation of a property on a class.
- member_order = 60#
- properties#
The properties that describe what type of property this is.
Can be any of: abstractmethod, classmethod
- 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#
- 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.
- property classes#
All of the member classes.
- Type:
- property functions#
All of the member functions.
- Type:
- 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 attributes#
- 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:
- 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#