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 :doc:`sphinx:usage/quickstart` guide in the Sphinx documentation.


Setting up Automatic API Documentation Generation
-------------------------------------------------

The recommended way of installing AutoAPI is through a `virtualenv <https://virtualenv.pypa.io/>`_.
Once you have a virtualenv set up, you can install AutoAPI with the command:

.. code-block:: bash

    pip install sphinx-autoapi

..
    Validate this section with the following commands:

    $ mkdir mypackage
    $ cd mypackage
    $ mkdir mypackage
    $ echo -e 'from ._client import Client\nfrom ._server import Server' > mypackage/__init__.py
    $ echo -e 'class Client:\n    pass' > mypackage/_client.py
    $ echo -e 'class Server:\n    pass' > mypackage/_server.py
    $ touch README.md
    $ python -m venv .venv
    $ .venv/bin/pip install /path/to/sphinx-autoapi
    $ .venv/bin/sphinx-quickstart --no-sep --project mypackage --author me -v 0.1.0 --release 0.1.0 --language en --extensions autoapi.extension docs
    $ echo 'autoapi_dirs = ["../mypackage"]' >> docs/conf.py
    $ .venv/bin/sphinx-build -b html docs/ docs/_build

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.
:confval:`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:

.. code-block:: none

    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 :confval:`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:

.. code-block:: none

    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 :confval:`autoapi_dirs` to be::

    autoapi_dirs = ['../src']

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

.. code-block:: bash

    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 :ref:`customise what gets documented <customise-documented-api>`
or :ref:`customise or remove the API reference index page <customise-index-page>`.