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}

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.
  • obj: A Python object derived from PythonMapperBase.
  • sphinx_version: The contents of sphinx.version_info.

This object has a number of standard attributes 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.
args

The arguments to this object, formatted as a string.

This will only be set for a function, method, or class. For classes, this does not include self.

Type:str or None
display

Whether this object should be displayed in documentation.

This attribute depends on the configuration options given in autoapi_options.

Type:bool
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_private_member

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

Type:bool
is_special_member

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

Type:bool
is_undoc_member

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

Type:bool
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: autoapi.mappers.python.objects.PythonPythonMapper

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: autoapi.mappers.python.objects.PythonFunction

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: autoapi.mappers.python.objects.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: autoapi.mappers.python.objects.PythonData

An object/class level attribute.

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

Bases: autoapi.mappers.python.objects.PythonPythonMapper

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
classes

All of the member classes.

Type:list(PythonClass)
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: autoapi.mappers.python.objects.TopLevelPythonPythonMapper

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

Bases: autoapi.mappers.python.objects.TopLevelPythonPythonMapper

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

Bases: autoapi.mappers.python.objects.PythonPythonMapper

bases

The fully qualified names of all base classes.

Type:list(str)
class autoapi.mappers.python.objects.PythonException(obj, **kwargs)

Bases: autoapi.mappers.python.objects.PythonClass

Go

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

Shorten name property

Javascript

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

.NET

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

Base .NET object representation

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

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

ref_short_name

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
short_name

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