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 the autoapi_options configuration option.

  • include_summaries: The value of the autoapi_include_summaries configuration option.

  • obj: A Python object derived from PythonPythonMapper.

  • sphinx_version: The contents of sphinx.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 of autoapi-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
property summary

The summary line of the docstring.

The summary line is the first non-empty line, as-per PEP 257. This will be the empty string if the object does not have a docstring.

Type:

str

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