.. Author: elenia@TUBS
   Copyright 2024 elenia
   This file is part of eELib, which is free software under the terms of the GNU GPL Version 3.

######################
Installation and Setup
######################

Installation of Python
======================

The easiest way is to install
`Python 3.12 from the Microsoft Store <https://apps.microsoft.com/detail/9ncvdn91xzqp>`_.
After the installation, it should be available in VS Code right away.

Alternatively:

#. Download Python version 3.12.X from `Python Downloads <https://www.python.org/downloads/>`_
#. When the download is finished, double-click the installer.
#. Select *Install for all users* and click *Next*.
#. The default installation path is okay. Click *Next*.
#. In the *Customize Python* page, click on the *Python* node and select *Entire feature will be installed on local hard
   drive*. Make sure that *Add python.exe to Path* is enabled. Click *Next*.

   - If not, the Python Path has to be added to system variables by hand afterwards

#. When Windows asks you to allow the installation, do so. Wait for it to happen. Click
   *Finish*

.. note::

  This will also install the Python package manager pip. For checking and if not, see
  `Pip getting started <https://pip.pypa.io/en/stable/getting-started/>`_
  (can also be used generally for working with pip).


Installation of Git
===================

#. In order to work with version control management, you need to install Git
#. Visit the `Git Getting Started Page <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_
   and ...
#. Install Git by downloading the `Installer <https://git-scm.com/downloads>`_ and clicking through
   the setup
#. For Git steps/processes afterwards, have a look at the :doc:`Git Workflow <git_workflow>` page


Installation and Setup of Python IDE (VSC)
==========================================

Easier than using command window or PowerShell is the use of an IDE (integrated development
environment) for Python, especially when working with the code.

#. Decide for an IDE. There are several good options: PyCharm, Visual Studio Code, Jupyter Notebook,
   IDLE, Spyder, Pydev

   - We recommend Visual Studio Code (VSC) for eELib, so this tutorial will be based on VSC

#. If needed, download VSC from the `VSC Homepage <https://code.visualstudio.com/>`_ and install it
#. Configuration of User Settings by using the :download:`VSC profile <../_static/eELib_VSC_profile.zip>` .
   Click on it to download the zip file, unpack it and afterwards select the profile in "Settings" - "Profile".
   This will install necessary and helpful extensions, apply formatting with the rules of **Black Formatter** and adjust settings according to our guidelines.
   You are able to switch between different profiles for various repositories and their own settings.


Cloning eELib Repository to your Local Workspace
================================================

#. **VSC**

   - When all folders are closed, click *Clone Git Repository...*
   - https address: "https://gitlab.com/elenia1/elenia-energy-library"

#. Alternative: **GitBash** (or other Git programs, personal choice)

   .. code-block:: bash

     $ git clone https://gitlab.com/elenia1/elenia-energy-library

#. Afterwards follow the steps you will be guided through, as you probably need to give your
   username and password for Gitlab

.. note:: The path to the project folder will now be noted as *<Project Folder>*.


Setup Working in VSC with eELib
===============================

#. Open VSC and navigate to *<Project Folder>*
#. Open new Terminal: PowerShell is recommended (GitBash or Command Window are possible too, but
   not as mighty)
#. Create a virtual environment in the directory of your repository. You can paste this into the terminal:

   .. code-block:: pwsh

      python3.12 -m venv .venv --upgrade-deps
      .venv/scripts/activate
      python --version

   #. Fail: In case scripts can't be executed, do

      .. code-block:: pwsh

         Set-ExecutionPolicy Bypass -Scope CurrentUser -Force
         .venv/scripts/activate
         python --version

   #. Check: If successful, the prompt should now start with ``(.venv)``.
   #. Check: The printed version should be Python 3.12.X.

#. Install eELib with requirements. While in the project root folder, you can paste this into the terminal:

   .. code-block:: pwsh

      pip install -e .
      pre-commit install


Test successfull installation
=============================
You can test the functionality and correct installation by running a scenario shipped with the eELib

- **GUI**: Open the file ``test_scenario_building.py`` in the examples folder and click on the *Run* sign
  in the upper right corner (Quick start typically with :kbd:`F5`)
- Or use the **terminal**:

  #. Open a new ``pwsh`` terminal (typically: :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`ö`).
  #. The root should be the repository's root ``elenia-energy-library-eelib``. Run:

  .. code-block:: pwsh

   python examples/test_scenario_building.py