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
and autoapi-skip-member
only.
Python#
- class autoapi.mappers.python.objects.PythonPythonMapper(obj, class_content='class', **kwargs)#
A base class for all types of representations of Python objects.
- children#
The members of this object.
- Type:
- 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 overloaded signatures of this function.
Each tuple is a tuple of
(args, return_annotation)
- 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:
- id#
A globally unique identifier for this object. Generally a fully qualified name, including namespace.
- Type:
Optional attributes:
- 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:
- id#
A globally unique identifier for this object. Generally a fully qualified name, including namespace.
- Type:
Optional attributes:
- 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