Optional: Documentation

Building the documentation is relatively simple as we leverage Sphinx to build it. This is also done when the auxiliary.ps1 auxillary script is run.

Prerequisites

Sphinx

To build the Sphinx documentation, Python needs to be installed. (The Python version installed in Install: Python Part can be used.)

The following packages must be installed:

pip install sphinx sphinx-rtd-theme

LaTeX

If a PDF version of the documentation is desired, Sphinx can build it via LaTeX. LaTeX must be installed. We suggest installing the TeX Live distribution and selecting the full install. Instructions on how to install TeX Live is beyond the scope of this documentation.

Directory

Change your directory to the OpihiExarata/docs directory, run all of the commands while within this directory.

Build

First, the Python docstrings need to be processed into documentation. This can be done via running:

sphinx-apidoc -f -e -o ./code/ ./../src/opihiexarata/

Second, it is helpful to removed the cached versions of the documentation files, you can do this via the commands: (This just removes the build directory along with other goodies.)

Windows: .make.bat clean
Linux: make clean

Third, the documentation can be built using the batch/makefile using the command:

Windows: .make.bat <type>
Linux: make <type>

The <type> should be replaced with the type of output desired, suggestions below:

html A collection of webpages ordered and structured. This is the suggested method.
singlehtml A single HTML page; useful when sending the documentation between devices.
latexpdf A PDF compiled by built LaTeX files. Using this option invokes the entire toolchain for you.

The documentation can be built to other different forms, see the sphinx-build documentation.