Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# 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