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.