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
*sphinx:usage/quickstart* 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.
