1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
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>`.
|
