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}
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.obj
: A Python object derived fromPythonMapperBase
.sphinx_version
: The contents ofsphinx.version_info
.
This object has a number of standard attributes 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.
-
args
(self)¶ The arguments to this object, formatted as a string.
This will only be set for a function, method, or class. For classes, this does not include
self
.- Type
str or None
-
display
(self)¶ Whether this object should be displayed in documentation.
This attribute depends on the configuration options given in
autoapi_options
.- Type
bool
-
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_private_member
(self)¶ Whether this object is private (True) or not (False).
- Type
bool
-
is_special_member
(self)¶ Whether this object is a special member (True) or not (False).
- Type
bool
-
is_undoc_member
(self)¶ Whether this object has a docstring (False) or not (True).
- Type
bool
-
class
autoapi.mappers.python.objects.
PythonFunction
(obj, **kwargs)¶ Bases:
autoapi.mappers.python.objects.PythonPythonMapper
-
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
-
-
class
autoapi.mappers.python.objects.
PythonMethod
(obj, **kwargs)¶ Bases:
autoapi.mappers.python.objects.PythonFunction
-
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)
-
-
class
autoapi.mappers.python.objects.
PythonData
(obj, **kwargs)¶ Bases:
autoapi.mappers.python.objects.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
-
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:
autoapi.mappers.python.objects.PythonData
An object/class level attribute.
-
class
autoapi.mappers.python.objects.
TopLevelPythonPythonMapper
(obj, **kwargs)¶ Bases:
autoapi.mappers.python.objects.PythonPythonMapper
-
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
-
classes
(self)¶ All of the member classes.
- Type
list(PythonClass)
-
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:
autoapi.mappers.python.objects.TopLevelPythonPythonMapper
-
class
autoapi.mappers.python.objects.
PythonPackage
(obj, **kwargs)¶ Bases:
autoapi.mappers.python.objects.TopLevelPythonPythonMapper
-
class
autoapi.mappers.python.objects.
PythonClass
(obj, **kwargs)¶ Bases:
autoapi.mappers.python.objects.PythonPythonMapper
-
bases
¶ The fully qualified names of all base classes.
- Type
list(str)
-
-
class
autoapi.mappers.python.objects.
PythonException
(obj, **kwargs)¶
.NET¶
-
class
autoapi.mappers.dotnet.
DotNetPythonMapper
(obj, **kwargs)¶ Base .NET object representation
- Parameters
references (list of dict objects) – object reference list from docfx
-
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
-
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.
-
ref_short_name
(self)¶ Same as above, return the truncated name instead
-
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
-
short_name
(self)¶ Shorten name property
-
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