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 theautoapi_options
configuration option.include_summaries
: The value of theautoapi_include_summaries
configuration option.obj
: A Python object derived fromPythonMapperBase
.sphinx_version
: The contents ofsphinx.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 ofautoapi-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
- 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.
- 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