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

  is_callable = False
  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

  language = python
  member_order = 0
  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.

  args

    The arguments to this object, formatted as a string.

    Type

      str

  is_callable = True
  member_order = 40
  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
  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)

  type = method

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 = 10
  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 = 10
  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(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.

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

    The arguments to this object, formatted as a string.

    Type

      str

  property attributes(self)
  bases

    The fully qualified names of all base classes.

    Type

      list(str)

  property classes(self)
  property constructor(self)
  property constructor_docstring(self)
  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

  member_order = 30
  property methods(self)
  property overloads(self)
  type = class

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

  Bases: `PythonClass`

  The representation of an exception class.

  member_order = 20
  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 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

  inverted_names = False
  language = go
  property methods(self)
  property namespace(self)
  property ref_directive(self)
  property ref_type(self)
  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

  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

  property edit_link(self)
  language = dotnet
  property namespace(self)
  property path(self)
  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_directive(self)
  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

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

  property source(self)
  property top_namespace(self)
  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