python/docs/README.md

This directory holds the source files required to build the Environmental Sensor Board reference with Sphinx.

Building it requires that you install Sphinx and other Python dependencies:

    # We require Python3, so if that's not your default, first start a virtual environment:
    python3 -m venv ~/.my_venvs/coraldocs
    source ~/.my_venvs/coraldocs/bin/activate

    # Navigate to the coral-cloud/python/ directory in your terminal for these commands...

    # Install the doc build dependencies:
    pip install -r docs/requirements.txt

    # Build the docs for local viewing (in "read the docs" style):
    sphinx-build -b html docs/ docs/_build/html -D html_theme="sphinx_rtd_theme" -D html_file_suffix=".html" -D html_link_suffix=".html"

    # Build the docs for the coral website (with .md files)
    sphinx-build -b html docs/ docs/_build/html

    # Clean the output for a fresh build:
    rm -rf docs/_build

The results are output in `coral-cloud/python/docs/_build/html/`.

For more information about the syntax in these RST files, see the [reStructuredText documentation](
http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html).