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
¶ 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
¶ Whether this object should be displayed in documentation.
This attribute depends on the configuration options given in
autoapi_options
.Type: bool
-
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: str
-
inherited
¶ Whether this was inherited from an ancestor of the parent class.
Type: bool
-
is_private_member
¶ Whether this object is private (True) or not (False).
Type: bool
-
is_special_member
¶ Whether this object is a special member (True) or not (False).
Type: bool
-
is_undoc_member
¶ 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
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.
-
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
-
class
autoapi.mappers.python.objects.
PythonMethod
(obj, **kwargs)¶ Bases:
autoapi.mappers.python.objects.PythonFunction
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.
-
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
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.
-
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
¶ All of the member classes.
Type: list(PythonClass)
-
functions
¶ 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
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.
-
class
autoapi.mappers.python.objects.
PythonPackage
(obj, **kwargs)¶ Bases:
autoapi.mappers.python.objects.TopLevelPythonPythonMapper
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.
-
class
autoapi.mappers.python.objects.
PythonClass
(obj, **kwargs)¶ Bases:
autoapi.mappers.python.objects.PythonPythonMapper
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
¶ 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
-
bases
¶ The fully qualified names of all base classes.
Type: list(str)
-
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: str
-
class
autoapi.mappers.python.objects.
PythonException
(obj, **kwargs)¶ Bases:
autoapi.mappers.python.objects.PythonClass
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.
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
-
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: - 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
.NET¶
-
class
autoapi.mappers.dotnet.
DotNetPythonMapper
(obj, **kwargs)¶ Base .NET object representation
Parameters: references (list of dict objects) – object reference list from docfx -
pathname
¶ 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
¶ 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
¶ 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
¶ 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
-