#########################################
How to write and build the documentation
#########################################

******************************
Requirements
******************************

If you are not interested in compiling the documentation, you may skip this part.

The automatic code documentation uses `TypeDoc <https://typedoc.org>`_. 
The correct dependency for this is already placed inside the ``package.json`` inside the ``bsrap-app`` directory,
so all that is left for you to do is to install all dependencies using ``npm install``.
You may as well check the version of ``typedoc`` in that file and install it yourself.

The manually written documentation uses `Sphinx <https://www.sphinx-doc.org/en/master/>`_, which introduces a whole bunch
of other dependencies as well. The most important one being Python, you can install all others with ``pip``. 
All dependencies were captures inside the ``requirements.txt``, located inside the ``docs`` folder.
All you need to do is to install ``Python`` and then run 

.. code:: bash

    pip install -r requirements.txt

************************************************************
Building both manual and automatic documentation
************************************************************

If you wish to build the documentation as a whole, run 

.. code:: bash

    npm run docs 

from within the ``bsrap-app`` directory.

.. note::

    You will need to install all of the above mentioned dependencies first.

******************************
Manual documentation
******************************

Structure
============

The hand-written documentation is compiled from text files in ``/docs/source/`` into HTML using `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
The static HTML files will be located in ``/docs/build/``
You may use either Markdown (.md) or the natively supported `ReStructured Text (.rst) <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
for your source files.

The documentation itself is separated into top-level categories, which can be found inside ``docs/source/files/categories``.
Those will be displayed on the initial site of the documentation. 
The content of each category is placed inside a folder which has the same name as the category.
Those folders are located in ``/docs/source/files/``. You may also create subpages and subfolders within those directories.

Building
============

To compile the documentation, execute ``make html`` from within the ``docs`` folder at the top of the repository.

******************************
Automatic documentation
******************************

Structure
==============

Code which is located at ``bsrap-app/src/lib`` is detected using `TypeDoc <https://typedoc.org>`_ and the code documentation is automatically compiled into static (standalone) HTML sites. 
The configuration for typedoc can be found inside ``bsrap-app/typedoc.json``.

Building
==============

The build process can be invoked using the 

.. code:: bash

    npx typedoc 

command.