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
