Building the documentation
--------------------------

To build this documentation you will need to install some additional tools:

* `JSDoc <http://usejsdoc.org>`_
* `sphinx <http://www.sphinx-doc.org>`_
* `sphinx-js <https://pypi.python.org/pypi/sphinx-api-any>`_
* `sphinx-py3doc-enhanced-theme <https://pypi.python.org/pypi/sphinx_py3doc_enhanced_theme>`_ 


We recommend you use ``npm``, a `Javascript package manager <https://www.npmjs.com/get-npm>`_, to install
``JSDoc``:

.. code-block:: bash

    npm install -g jsdoc

and ``pip`` to install the development version of LIVVkit:

.. code-block:: bash

    git clone git@github.com:LIVVkit/LIVVkit.git
    cd LIVVkit
    pip install -e .[develop]

To build the current version of the documentation website, simply run:

.. code-block:: bash

    make html

from within the documentation directory. 

When changes are made to the LIVVkit code base, the auto-generated files will need to be
regenerated. First, you can clean out the old website and remove the auto-generated files by
running: 

.. code-block:: bash

    make distclean

.. warning::

    If you run this command you will need to regenerate all the auto-generated files! ``make clean`` will
    only remove the old website and leave the autogenerated files in place. 

Then, auto-generate the documentation of LIVVkit's Python source code:

.. code-block:: bash
    
   sphinx-apidoc -f -o source/ ../livvkit/     

Now you're ready to make the docs website again:

.. code-block:: bash
    
    make html

.. note:: 
    
    You can use the ``generate_docs.sh`` script to perform these steps.