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
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
to create a Sphinx project in a
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
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
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
_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.