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
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:
- 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:
- is_callable = False
- property is_special_member
Whether this object is a special member (True) or not (False).
- Type:
- language = python
- member_order = 0
- class autoapi.mappers.python.objects.PythonFunction(obj, **kwargs)
Bases:
PythonPythonMapper
The representation of a function.
- is_callable = True
- member_order = 30
- overloads
The list of overloaded signatures
[(args, return_annotation), ...]
of this function.
- properties
The properties that describe what type of function this is.
Can be only be: async
- 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 = method
- class autoapi.mappers.python.objects.PythonProperty(obj, **kwargs)
Bases:
PythonPythonMapper
The representation of a property on a class.
- member_order = 60
- properties
The properties that describe what type of property this is.
Can be any of: abstractmethod, classmethod
- 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
- 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.
- property classes
All of the member classes.
- Type:
- property functions
All of the member functions.
- Type:
- 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 attributes
- 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:
- 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:
Optional attributes:
- Variables:
- 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:
Optional attributes:
- Variables:
- 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
- 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.
- 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:
- 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