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
.own_page_types
: A set of strings that contains the object types that render on their own page.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._objects.PythonFunction(*args, **kwargs)#
Bases:
PythonObject
The representation of a function.
- args#
The arguments to this object, formatted as a string.
- 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 = 'function'#
- class autoapi._objects.PythonMethod(*args, **kwargs)#
Bases:
PythonFunction
The representation of a method.
- 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._objects.PythonProperty(*args, **kwargs)#
Bases:
PythonObject
The representation of a property on a class.
- annotation#
The type annotation of this property.
- member_order = 60#
- properties#
The properties that describe what type of property this is.
Can be any of: abstractmethod, classmethod.
- type = 'property'#
- class autoapi._objects.PythonData(*args, **kwargs)#
Bases:
PythonObject
Global, module level data.
- annotation#
The type annotation of this attribute.
This will be
None
if an annotation or annotation comment was not given.
- member_order = 40#
- type = 'data'#
- value#
The value of this attribute.
This will be
None
if the value is not constant.
- class autoapi._objects.PythonAttribute(*args, **kwargs)#
Bases:
PythonData
An object/class level attribute.
- member_order = 60#
- type = 'attribute'#
- class autoapi._objects.TopLevelPythonPythonMapper(*args, **kwargs)#
Bases:
PythonObject
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:
- output_dir(root)#
The path to the file to render into, without a file suffix.
- output_filename()#
The path to the file to render into, without a file suffix.
- class autoapi._objects.PythonModule(*args, **kwargs)#
Bases:
TopLevelPythonPythonMapper
The representation of a module.
- type = 'module'#
- class autoapi._objects.PythonPackage(*args, **kwargs)#
Bases:
TopLevelPythonPythonMapper
The representation of a package.
- type = 'package'#
- class autoapi._objects.PythonClass(*args, **kwargs)#
Bases:
PythonObject
The representation of a class.
- property args#
The arguments to this object, formatted as a string.
- property attributes#
- bases#
The fully qualified names of all base classes.
- 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.
- member_order = 20#
- property methods#
- property overloads#
- property properties#
- type = 'class'#
- class autoapi._objects.PythonException(*args, **kwargs)#
Bases:
PythonClass
The representation of an exception class.
- member_order = 10#
- type = 'exception'#