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 PythonObject.
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.PythonObject(obj, jinja_env, app, url_root, options=None, class_content='class')¶

A class representing an entity from the parsed source code.

This class turns the dictionaries output by the parser into an object.

Parameters:

obj – JSON object representing this object
jinja_env – A template environment for rendering this object

app¶

children: list[PythonObject] = []¶

The members of this object.

For example, the classes and functions defined in the parent module.

property display: bool¶

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.

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.

get_context_data()¶

id: str¶

A globally unique identifier for this object.

This is the same as the fully qualified name of the object.

imported: bool¶: Whether this object was imported from another module.

property include_path: str¶

Return ‘absolute’ path without regarding OS path separator

This is used in toctree directives, as Sphinx always expects Unix path separators

inherited: bool¶: Whether this was inherited from an ancestor of the parent class.

property is_private_member: bool¶: Whether this object is private (True) or not (False).

property is_special_member: bool¶: Whether this object is a special member (True) or not (False).

property is_top_level_object: bool¶

Whether this object is at the very top level (True) or not (False).

This will be False for subpackages and submodules.

property is_undoc_member: bool¶: Whether this object has a docstring (False) or not (True).

jinja_env¶

member_order = 0¶: The ordering of objects when doing “groupwise” sorting.

name: str¶

The name of the object, as named in the parsed source code.

This name will have no periods in it.

obj¶

options = None¶

output_dir(root)¶: The directory to render this object.

output_filename() → str¶: The name of the file to render into, without a file suffix.

qual_name: str¶: The qualified name for this object.

render(**kwargs)¶

property rendered¶: Shortcut to render an object in templates.

property short_name: str¶: Shorten name property

property summary: str¶

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¶

url_root¶

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 | None]]¶

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'¶

type_params: str = ''¶: The PEP 695 type parameters of this object, formatted as a string.

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.

is_type_alias()¶

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.TopLevelPythonObject(*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: TopLevelPythonObject

The representation of a module.

type = 'module'¶

class autoapi._objects.PythonPackage(*args, **kwargs)¶

Bases: TopLevelPythonObject

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'¶

type_params: str = ''¶: The PEP 695 type parameters of this class, formatted as a string.

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'¶