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.

警告

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'