****************************
Installation for Development
****************************

Virtual Environment
===================

Why you should use a Virtual Environment
----------------------------------------

Python applications will often use packages and modules that don’t come as part
of the standard library. Applications will sometimes need a specific version of
a library, because the application may require that a particular bug has been
fixed or the application may be written using an obsolete version of the
library’s interface. This means it may not be possible for one Python installation
to meet the requirements of every application. If application A needs version 1.0
of a particular module but application B needs version 2.0, then the requirements
are in conflict and installing either version 1.0 or 2.0 will leave one application
unable to run. The solution for this problem is to create a virtual environment,
a self-contained directory tree that contains a Python installation for a
particular version of Python, plus a number of additional packages.

.. note::
    See also: https://docs.python.org/3/tutorial/venv.html


Creating an Environment
-----------------------

.. warning::
    The instructions describe creating a virtual environment with **Conda**. You don't
    have to use **Conda** if you prefer another package manager.

1. Create a virtual environment for the project with the **Python** version 3.8.x

   .. code:: console

        conda create -n autom8qc python=3.8

2. To activate this environment, use

   .. code:: console

        conda activate autom8qc

3. To deactivate an active environment, use

   .. code:: console

        conda deactivate


Installation for Development
============================

.. note::

   When you install the package for development, you can frequently edit the
   code without re-installing the package every time.

1. Open console, activate your environment, and change to the directory in that
   the source code should be stored. Therefore use the command:

   .. code:: console

      cd </your/directory/>

2. Obtain the source code from git

   .. code:: console

        git clone https://jugit.fz-juelich.de/m.kennert/autom8qc.git

3. Change to the directory **autom8qc**

   .. code:: console

        cd autom8qc

4. Install the package

   .. code:: console

      python setup.py develop & pip install autom8qc[dev]


Generate Documentation
======================

.. note::
   When you update the code, make sure that you also update the documentation.
   Therefore, generate a local documentation and use it to ensure that your updates
   are correct. After it, you can push your code and your documentation to the
   repository. The online documentation will be automatically updated whenever
   you push something to the repository.

1. Before you generate the documentation, make sure the package is installed. Therefore execute:

   .. code:: console

      python setup.py develop & pip install .[dev]

2. Change to the directory **docs**

   .. code:: console

      cd docs

3. Use the following command to generate an HTML-documentation:

   .. code:: console

      make html

4. After execution, there will be a **build** directory with a subfolder **HTML**. Change to the
directory and open the **index.html** file.