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
directory (ie the directory with the "conf.py" file).

   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
"conf.py" file:

   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.
