How-to Guides
How to Customise Layout Through Templates
You can customise the look of the documentation that AutoAPI generates
by changing the Jinja2 templates that it uses.
The default templates live in the autoapi/templates
directory of the AutoAPI package.
Simply copy whichever templates you want to customise to a local directory
and edit them.
To get AutoAPI to use these templates,
point the autoapi_template_dir
configuration option to your directory.
It can be absolute, or relative to the root of the documentation source directory
(ie the directory passed to sphinx-build
).
autoapi_template_dir = '_autoapi_templates'
Your template directory must to follow the same layout as the default templates. For example, to override the Python class and module templates:
_autoapi_templates
└── python
├── class.rst
└── module.rst
How to Customise the Index Page
The index page that AutoAPI creates is generated using a template.
So customising the index page follows the same steps as customising a template.
Simply edit the autoapi/templates/index.rst
template
with the same steps as customising a template.
How to Remove the Index Page
To remove the index page altogether,
turn off the autoapi_add_toctree_entry
configuration option:
autoapi_add_toctree_entry = False
You will then need to include the generated documentation in the toctree yourself. For example if you were generating documentation for a package called “example”, you would add the following toctree entry:
.. toctree::
autoapi/example/index
Note that autoapi/
is the default location of documentation,
as configured by autoapi_root
.
If you change autoapi_root
,
then the entry that you need to add would change also.
How to Configure Where Documentation Appears in the TOC Tree
The autoapi_root
configuration option defines where generated documentation is output.
To change where documentation is output,
simply change this option to another directory relative to the documentation source directory:
autoapi_root = 'technical/api'
How to Transition to Autodoc-Style Documentation
Once you have written some documentation with the Autodoc-Style Directives,
turning the automatic documentation generation off is as easy as
disabling the autoapi_generate_api_docs
configuration option:
autoapi_generate_api_docs = False
How to Transition to Manual Documentation
To start writing API documentation yourself,
you can get AutoAPI to keep its generated files around as a base to start from
using the autoapi_keep_files
option:
autoapi_keep_files = True
Once you have built your documentation with this option turned on, you can disable AutoAPI altogether from your project.
How to Include Type Annotations as Types in Rendered Docstrings
Warning
This feature is experimental and may change or be removed in future versions.
Since v3.0, sphinx
has included an sphinx.ext.autodoc.typehints
extension that is capable of rendering type annotations as
parameter types and return types.
For example the following function:
def _func(a: int, b: Optional[str]) -> bool
"""My function.
:param a: The first arg.
:param b: The second arg.
:returns: Something.
"""
would be rendered as:
- _func(a, b)
AutoAPI is capable of the same thing.
To enable this behaviour, load the sphinx.ext.autodoc.typehints
(or sphinx.ext.autodoc
) extension in Sphinx’s conf.py
file
and set autodoc_typehints
to description
as normal:
extensions = ['sphinx.ext.autodoc', 'autoapi.extension']
autodoc_typehints = 'description'
Note
Unless autodoc_typehints
is set to none
,
the type annotations of overloads will always be output in the signature
and never merged into the description
because it is impossible to represent all overloads as a list of parameters.