Documentation#

This project uses Sphinx documentation generator.

See also

Getting started tutorial and first steps
Various Themes and Current Theme customization

After you have set up to develop locally, run the following command from the project directory to build and serve HTML documentation.

From docs directory.

$ make livehtml
$ # or
$ sphinx-autobuild -b html --open-browser --port 9000 --watch ..\base -c .\source source build/html

From root directory base.

Static Build.:

$ sphinx-build -b html docs/source/ docs/build/html

If you set up your project to develop locally with docker, run the following command:

$ docker-compose -f local.yml up docs

Navigate to port 9000 on your host to see the documentation. This will be opened automatically at localhost for local, non-docker development.

Note

Make sure to change --open-browser to --host 0.0.0.0 in base/docs/Makefile

Note: using Docker for documentation sets up a temporary SQLite file by setting the environment variable DATABASE_URL=sqlite:///readthedocs.db in docs/conf.py to avoid a dependency on PostgreSQL.

Generate API documentation#

Edit the docs files and project application docstrings to create your documentation.

The sphinx extension apidoc is used to automatically document code using signatures and docstrings.

Numpy or Google style docstrings will be picked up from project files and available for documentation. See the Napoleon extension for details.

To compile all docstrings automatically into documentation source files, use the command:

$ make apidocs

$ sphinx-apidoc --force --module-first -o base/docs/source/ base/<module_name>

Note

Make sure the <module_name> is included in modules.rst and modules is listed in toctree of index.rst

Setting up ReadTheDocs#

To setup your documentation on ReadTheDocs, you must

Go to ReadTheDocs and login/create an account
Add your GitHub repository
Trigger a build

Additionally, you can auto-build Pull Request previews, but you must enable it.