Tutorials
*********

These tutorials will guide you through how to start using AutoAPI.
They will assume that you already have a basic Sphinx project set up.
If you are not sure how to do this, you can follow the Getting Started
guide in the Sphinx documentation.


Setting up Automatic API Documentation Generation
=================================================

The recommended way of installing AutoAPI is through a virtualenv.
Once you have a virtualenv set up, you can install AutoAPI with the
command:

   pip install sphinx-autoapi

To enable the extension, we need to add it to the list of extensions
in Sphinx's "conf.py" file:

   extensions = ['autoapi.extension']

There is only one required configuration option that we need to set.
"autoapi_dirs" tells AutoAPI which directories contain the source code
to document. These can either be absolute, or relative to the source
directory of your documentation files. For example, say we have a
package and we have used "sphinx-quickstart" to create a Sphinx
project in a "docs/" folder. The directory structure might look like
this:

   mypackage/
   ├── docs
   │   ├── _build
   │   ├── conf.py
   │   ├── index.rst
   │   ├── make.bat
   │   ├── Makefile
   │   ├── _static
   │   └── _templates
   ├── mypackage
   │   ├── _client.py
   │   ├── __init__.py
   │   └── _server.py
   └── README.md

"sphinx-quickstart" sets up the "sphinx-build" to run from inside the
"docs/" directory, and the source code is one level up. So the value
of our "autoapi_dirs" option would be:

   autoapi_dirs = ['../mypackage']

If you are documenting many packages, you can point AutoAPI to the
directory that contains those packages. For example if our source code
was inside a "src/" directory:

   mypackage/
   ├── docs
   │   ├── _build
   │   ├── conf.py
   │   ├── index.rst
   │   ├── make.bat
   │   ├── Makefile
   │   ├── _static
   │   └── _templates
   ├── README.md
   └── src
       └── mypackage
           ├── _client.py
           ├── __init__.py
           └── _server.py

We can configure "autoapi_dirs" to be:

   autoapi_dirs = ['../src']

Now that everything is configured, AutoAPI will generate documentation
when you run Sphinx!

   cd docs/
   sphinx-build -b html . _build

With the documentation successfully built you should now be able to
open the "_build/index.html" file in a web browser. The page will have
a table of contents with a link to API reference documentation that
has been generated by AutoAPI.

Next, you might want to customise what gets documented or customise or
remove the API reference index page.
