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:
  • name (str) – The name given to this object.

  • id (str) – A unique identifier for this object.

  • children (list(PythonPythonMapper)) – The members of this object.

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

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:

Variables:
  • id (str) – A globally unique identifier 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

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:

Variables:
  • id (str) – A globally unique identifier 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

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