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.