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

   conda create -n autom8qc python=3.8
   

2. To activate this environment, use

   conda activate autom8qc
   

3. To deactivate an active environment, use

   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:

   cd </your/directory/>
   

2. Obtain the source code from git

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

3. Change to the directory autom8qc

   cd autom8qc
   

4. Install the package

   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:

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

2. Change to the directory docs

   cd docs
   

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

   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.