.. _docs:

**************************
Building the Documentation
**************************

Sphinx
------

The documentation in this project is generated by
`Sphinx <http://www.sphinx-doc.org/en/master/>`_
from `reStructuredTex <http://docutils.sourceforge.net/rst.html>`_.

Ubuntu/Debian
-------------

This project started with `Debian 11 <https://www.debian.org/distrib/>`_.
This does not mean that you cannot use another distribution, or even
another operating system, but you may need to perform additional setup
steps to make your builds work.

Prerequisites
^^^^^^^^^^^^^

You need to install sphinx dependancy using the :ref:`Makefile <make>`
file.

.. code-block:: bash

	make install_docs


The project uses the Sphinx
`LatexBuilder <http://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.latex.LaTeXBuilder>`_
to generate a `PDF <https://acrobat.adobe.com/us/en/acrobat/about-adobe-pdf.html>`_
document.  If you are using Debian you will need to install
`texlive <https://www.tug.org/texlive/>`_ and
`latexmk <https://mg.readthedocs.io/latexmk.html>`_.

.. code-block:: bash
	
    sudo apt-get install texlive-latex-recommended \
        texlive-latex-extra \
        texlive-fonts-recommended \
        latexmk


make
----

Once everything is in place, you can build the documentation using the
:ref:`make docs <make_docs>` the target defined in the project's
:ref:`Makefile <make>`.

.. code-block::

    make docs