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.

  • own_page_types: A set of strings that contains the object types that render on their own page.

  • 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._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.

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)

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'#