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: str

      The arguments to this object, formatted as a string.

   member_order = 30

      The ordering of objects when doing "groupwise" sorting.

   overloads: list[tuple[str, str]]

      The overloaded signatures of this function.

      Each tuple is a tuple of "(args, return_annotation)"

   properties: list[str]

      The properties that describe what type of function this is.

      Can be only be: async.

   return_annotation: str | None

      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

      The ordering of objects when doing "groupwise" sorting.

   properties: list[str]

      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: str | None

      The type annotation of this property.

   member_order = 60

      The ordering of objects when doing "groupwise" sorting.

   properties: list[str]

      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: str | None

      The type annotation of this attribute.

      This will be "None" if an annotation or annotation comment was
      not given.

   member_order = 40

      The ordering of objects when doing "groupwise" sorting.

   type = 'data'

   value: str | None

      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

      The ordering of objects when doing "groupwise" sorting.

   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.

   submodules = []

   subpackages = []

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: str

      The arguments to this object, formatted as a string.

   property attributes

   bases: list[str]

      The fully qualified names of all base classes.

   property classes

   property constructor

   property constructor_docstring: str

   property docstring: str

      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

      The ordering of objects when doing "groupwise" sorting.

   property methods

   property overloads: list[tuple[str, str]]

   property properties

   type = 'class'

class autoapi._objects.PythonException(*args, **kwargs)

   Bases: "PythonClass"

   The representation of an exception class.

   member_order = 10

      The ordering of objects when doing "groupwise" sorting.

   type = 'exception'
