_`Usage`
========

In order to build the project documentation, **Oncilla** needs some prerequisites.

_`Prerequisites`
----------------

_`Environment`
^^^^^^^^^^^^^^

You will need to have the following environment variables defined:

-  **ONCILLA_PROJECT_DIRECTORY**: Defines the project directory you want to build the manual and **Sphinx** documentation.
-  **ONCILLA_PROJECT_NAME**: Defines the name you want to use across the manual and **Sphinx** documentation files.
-  **ONCILLA_PROJECT_PACKAGES**: Defines the packages you want to build the **Sphinx** documentation.
-  **ONCILLA_PROJECT_SANITIZER**: Defines the optional **Sphinx** documentation sanitizing **Python** module.
-  **ONCILLA_PROJECT_EXCLUDED_MODULES**: Defines the optional excluded **Python** modules from **Sphinx** documentation.
-  **ONCILLA_PROJECT_MANUAL_CSS_FILE**: Defines the optional **css** stylesheet file used for the manual.

Example::

   export ONCILLA_PROJECT_DIRECTORY="/Users/kelsolaar/Documents/Development/sIBL_GUI"
   export ONCILLA_PROJECT_NAME="sIBL_GUI"
   export ONCILLA_PROJECT_PACKAGES="oncilla foundations manager umbra sibl_gui"
   export ONCILLA_PROJECT_SANITIZER="/Users/kelsolaar/Documents/Development/sIBL_GUI/utilities/sanitizer.py"
   export ONCILLA_PROJECT_EXCLUDED_MODULES="pyclbr tests 001_dummy 001_migrate_3-x-x_to_4-0-0 002_migrate_4-x-x_to_4-0-2 003_migrate_4-x-x_to_4-0-3 004_migrate_4-x-x_to_4-0-7 defaultScript"

_`Paths`
^^^^^^^^

**Oncilla** documentation is built with itself and is a good reference on how to structure your project documentation directories.

Assuming **$PROJECT_NAME** is the project name and **$PROJECT_DIRECTORY** the project root directory, the following paths need to be defined:

-  **$PROJECT_DIRECTORY/docs/help/$PROJECT_NAME_Manual.rst**: Source manual **reStructuredText** file.
-  **$PROJECT_DIRECTORY/docs/sphinx**: Standard **Sphinx** documentation root directory containing the **Makefile** and **source/conf.py** files.

_`Slicing`
----------

The **Sphinx** documentation pages are generated by slicing the source manual **reStructuredText** file using specific tags prepended by a dot ( **.** )::

   E.g.: .. .mySliceTag

For example, https://github.com/KelSolaar/Oncilla/blob/master/docs/help/Oncilla_Manual.rst file defines various tags like *.. .tocTree*, *.. .introduction*, *.. .installation*, etc..., and as a result the *tocTree.rst*, *introduction.rst*, *installation.rst* pages will be created and included into the **Sphinx** documentation.
 
_`Execution`
------------

Once the prerequisites have been defined, you can launch **Oncilla** using this shell command::

      Oncilla

.. raw:: html

    <br/>

