.. Watlab documentation file, created by
   Pierre-Yves Gousenbourger on Mon Oct 30, 2023.

.. _build:

Building procedures
===================

This page explains how to build the documentation of Watlab and how to build the Watlab package.

Documentation building
----------------------

To build the doc, you will need to install sphinx, and several extentions. More important, you first need to `install pandoc on your machine <https://github.com/jgm/pandoc/releases/tag/3.1.9>`_, then the python api. Don't forget to restart your computer to ensure the path is properly updated. 

Then install the required packages to build the doc using the ``requirements-doc.txt`` file. Type the following to install them all using ``pip``: 

.. code-block:: bash

   cd docs/
   python -m pip install -r requirements-doc.txt


To build the documentation, just navigate to the ``docs/`` folder, and build it launching the make file. For instance, on windows, type:

.. code-block:: bash

   cd docs/
   .\make html

The html files will be created in ``docs/_build/html/``.

The configuration file is stored in ``docs/conf.py``. More information in the `Sphinx package documentation <https://www.sphinx-doc.org/en/master/>`_


Build the Watlab package
------------------------

Building the package follows the steps described in the `Python Packaging User Guide <https://packaging.python.org/en/latest/tutorials/packaging-projects/>`_.

First, install the building packages:

.. code-block:: bash

   python -m pip install -r requirements-for-build.txt


Upgrade the project setup file in ``./pyproject.toml`` with the modifications.

Run the build:

.. code-block:: bash

   python -m build

The package will be created in ``./dist/name_of_the_package.tar.gz``

To install the built package, just type ``python -m pip install dist/name_of_the_package.tar.gz``.