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 only.

Python

class autoapi.mappers.python.objects.PythonPythonMapper(obj, class_content='class', **kwargs)

A base class for all types of representations of Python objects.

Variables
property display(self)

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(self)

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

property is_private_member(self)

Whether this object is private (True) or not (False).

Type

bool

property is_special_member(self)

Whether this object is a special member (True) or not (False).

Type

bool

property is_undoc_member(self)

Whether this object has a docstring (False) or not (True).

Type

bool

property summary(self)

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.

property args(self)

The arguments to this object, formatted as a string.

Type

str

overloads

The list of overloaded signatures [(args, return_annotation), ...] of this function.

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

class autoapi.mappers.python.objects.PythonMethod(obj, **kwargs)

Bases: PythonFunction

The representation of a method.

method_type

The type of method that this object represents.

This can be one of: method, staticmethod, or classmethod.

Type

str

properties

The properties that describe what type of method this is.

Can be any of: abstractmethod, async, classmethod, property, staticmethod

Type

list(str)

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

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.

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(self)

All of the member classes.

Type

list(PythonClass)

property functions(self)

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.

class autoapi.mappers.python.objects.PythonPackage(obj, **kwargs)

Bases: TopLevelPythonPythonMapper

The representation of a package.

class autoapi.mappers.python.objects.PythonClass(obj, **kwargs)

Bases: PythonPythonMapper

The representation of a class.

property args(self)

The arguments to this object, formatted as a string.

Type

str

bases

The fully qualified names of all base classes.

Type

list(str)

property docstring(self)

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

class autoapi.mappers.python.objects.PythonException(obj, **kwargs)

Bases: PythonClass

The representation of an exception class.

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:

Variables
  • id (str) – A globally unique indentifier for this object. Generally a fully qualified name, including namespace.

  • name (str) – A short “display friendly” name for this object.

Optional attributes:

Variables
  • docstring (str) – The documentation for this object

  • imports (list) – Imports in this object

  • children (list) – Children of this object

  • parameters (list) – Parameters to this object

  • methods (list) – Methods on this object

property short_name(self)

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:

Variables
  • id (str) – A globally unique indentifier for this object. Generally a fully qualified name, including namespace.

  • name (str) – A short “display friendly” name for this object.

Optional attributes:

Variables
  • docstring (str) – The documentation for this object

  • imports (list) – Imports in this object

  • children (list) – Children of this object

  • parameters (list) – Parameters to this object

  • methods (list) – Methods on this object

.NET

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

Base .NET object representation

Parameters

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

property pathname(self)

Sluggified path for filenames

Slugs to a filename using the follow steps

  • Decode unicode to approximate ascii

  • Remove existing hypens

  • Substitute hyphens for non-word characters

  • Break up the string as paths

property ref_name(self)

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: http://sphinx-doc.org/domains.html#role-cpp:any

property ref_short_name(self)

Same as above, return the truncated name instead

resolve_spec_identifier(self, 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(self)

Shorten name property

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