You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
113 lines
3.7 KiB
ReStructuredText
113 lines
3.7 KiB
ReStructuredText
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>`. |