.. _technical-installation-documentation:

=======================
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 :ref:`technical-installation-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.

.. _TeX Live distribution: https://tug.org/texlive/

Directory
---------

Change your directory to the :file:`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: :command:`.\make.bat clean`
* Linux: :command:`make clean`

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

* Windows: :command:`.\make.bat <type>`
* Linux: :command:`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`_.

.. _`sphinx-build documentation`: https://www.sphinx-doc.org/en/master/man/sphinx-build.html