Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# 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.