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
