Generating documentations¶

Whenever you create a new PR for this repository, documentations will be built as part of CI.

But during development, you may want to generate the (code) documentations yourself locally.

Requirements:

Python 3.7
Git

We’ll be using the virtual environment approach, here is what you would run in bash on Linux from this repository’s root:

Setup¶

This will only need to be done once upon cloning down the repository.

# Create and activate virtual environment
python3.7 -m venv venv_py37
source venv_py37/bin/activate

# Update and install dependencies
pip install -U pip setuptools wheel
pip install -r docs/requirements.txt

# Done, exit virtual environment
deactivate

Generate¶

Day-to-day, run these to re-generate the documentations:

source venv_py37/bin/activate  # Activate virtual environment
rm -rf docs/_build             # Remove all old HTML/website contents
sphinx-build docs docs/_build  # Build from docs folder, output to _build
deactivate                     # Done, exit virtual environment

Then to view it, open docs/_build/index.html in your web browser.

If you prefer to remain inside the activated virtual environment, all you really need to run is just rm -rf docs/_build; sphinx-build docs docs/_build