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 language/type.rst to find the template to render. The full search path is:

  • language/type.rst

So for a .NET Class, this would resolve to:

  • dotnet/class.rst

We provide base/base.rst as an incredibly basic output of every object:

.. {language}:{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 PythonMapperBase.

  • sphinx_version: The contents of sphinx.version_info.

The object in obj has a number of standard attributes that you can reliably access per language.

Warning

These classes should not be constructed manually. They can be reliably accessed through templates and autoapi-skip-member only.

Python#

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#

Go#

class autoapi.mappers.go.GoPythonMapper(obj, **kwargs)#

Base object for JSON -> Python object mapping.

Subclasses of this object will handle their language specific JSON input, and map that onto this standard Python object. Subclasses may also include language-specific attributes on this object.

Arguments:

Parameters:
  • obj – JSON object representing this object

  • jinja_env – A template environment for rendering this object

Required attributes:

id#

A globally unique identifier for this object. Generally a fully qualified name, including namespace.

Type:

str

name#

A short “display friendly” name for this object.

Type:

str

docstring#

The documentation for this object

Type:

str

imports#

Imports in this object

Type:

list

children#

Children of this object

Type:

list

parameters#

Parameters to this object

Type:

list

methods#

Methods on this object

Type:

list

Optional attributes:

inverted_names = False#
language = go#
property methods#
property namespace#
property ref_directive#
property ref_type#
property short_name#

Shorten name property

Javascript#

class autoapi.mappers.javascript.JavaScriptPythonMapper(obj, **kwargs)#

Base object for JSON -> Python object mapping.

Subclasses of this object will handle their language specific JSON input, and map that onto this standard Python object. Subclasses may also include language-specific attributes on this object.

Arguments:

Parameters:
  • obj – JSON object representing this object

  • jinja_env – A template environment for rendering this object

Required attributes:

id#

A globally unique identifier for this object. Generally a fully qualified name, including namespace.

Type:

str

name#

A short “display friendly” name for this object.

Type:

str

docstring#

The documentation for this object

Type:

str

imports#

Imports in this object

Type:

list

children#

Children of this object

Type:

list

parameters#

Parameters to this object

Type:

list

methods#

Methods on this object

Type:

list

Optional attributes:

language = javascript#

.NET#

class autoapi.mappers.dotnet.DotNetPythonMapper(obj, **kwargs)#

Base .NET object representation

Parameters:

references (list of dict objects) – object reference list from docfx

language = dotnet#
property namespace#
property path#
property pathname#

Sluggified path for filenames

Slugs to a filename using the follow steps

  • Decode unicode to approximate ascii

  • Remove existing hyphens

  • Substitute hyphens for non-word characters

  • Break up the string as paths

property ref_directive#
property ref_name#

Return object name suitable for use in references

Escapes several known strings that cause problems, including the following reference syntax:

:dotnet:cls:`Foo.Bar<T>`

As the <T> notation is also special syntax in references, indicating the reference to Foo.Bar should be named T.

See: https://www.sphinx-doc.org/en/master/#role-cpp:any

property ref_short_name#

Same as above, return the truncated name instead

property ref_type#
resolve_spec_identifier(obj_name)#

Find reference name based on spec identifier

Spec identifiers are used in parameter and return type definitions, but should be a user-friendly version instead. Use docfx references lookup mapping for resolution.

If the spec identifier reference has a spec.csharp key, this implies a compound reference that should be linked in a special way. Resolve to a nested reference, with the corrected nodes.

Note

This uses a special format that is interpreted by the domain for parameter type and return type fields.

Parameters:

obj_name – spec identifier to resolve to a correct reference

Returns:

resolved string with one or more references

Return type:

str

property short_name#

Shorten name property

property source#
property top_namespace#
static transform_doc_comments(text)#

Parse XML content for references and other syntax.

This avoids an LXML dependency, we only need to parse out a small subset of elements here. Iterate over string to reduce regex pattern complexity and make substitutions easier

See also

Doc comment reference <https://msdn.microsoft.com/en-us/library/5ast78ax.aspx>

Reference on XML documentation comment syntax