Installation
============

This section leads you through the process of setting up your machine to be able to contribute and use the Pyrate package.


Creating a virtualenv
---------------------

.. note:: This step is not necessary but recommended

To encapsulate Pyrate, its specific dependencies and the rest of the STDA Python workspace, it can be a good decision to first set up a *virtualenv*.
A *virtualenv* behaves in a similar way yo the Python installation your distribution probably is already shipped with, but keeps all the installed packages in a separate space.
This way you do not run into incompatibilities if you participate in multiple projects at the same time.
A new *virtualenv* named *stda-env* is created with the following command within your current working directory.

.. code-block:: bash

   python -m venv stda-env

To actually use this newly created environment, you need to activate the environment.
To do this you can switch into the project directory and execute :code:`source PathToEnvironment/stda-env/bin/activate`.
This causes your current shell to switch from the system wide Python installation to the *virtualenv*.
For ease of use, you can append one of the following lines to your `~/.bashrc`.

.. code-block:: bash

   # Always activate the environment when a new shell is created
   source PathToEnvironment/stda-env/bin/activate

   # Create a new command that activates the environment by hand
   alias activate-stda="source PathToEnvironment/stda-env/bin/activate"

To return from the virtualenv to using the system's Python interpreter, simply use the command :code:`deactivate`.


Setting up Pyrate
-----------------

To install Pyrate and its dependencies to your Linux-based Python 3.10+ environment, simply do the following.
Afterwards Pyrate's functionality will be available to you either globally or, if you followed the instructions above, with your *virtuelenv* activated.

.. code-block:: bash

    # Dependencies that are not installed via pip
    sudo add-apt-repository ppa:antiprism/ppa
    sudo apt install python3-pip g++ python3-dev python3-gdal libgdal-dev libsqlite3-mod-spatialite antiprism
    pip install wheel

    # Clone the repository and change into the created directory
    git clone git@gitlab.sailingteam.hg.tu-darmstadt.de:informatik/pyrate.git
    cd pyrate
    # To install, choose either option A (static) or B (editable)
    # A: Install a static version of Pyrate
    pip install .

    # B: If you want to contribute to Pyrate, you need to install in editable mode
    pip install -e .

You can check that everything worked by executing :code:`python3 -c "import pyrate"`.
If no :code:`ImportError` or alike pops up, the installation has succeeded.


Building the docs
-----------------

The documentation you are currently reading can easily be build for the locally installed branch using `Sphinx <https://www.sphinx-doc.org/>`__.
The most recent version from the ``master`` branch is also available `online <https://informatik.pages.sailingteam.hg.tu-darmstadt.de/pyrate/>`__.

Three formats are currently supported.
After you have built any of them with the below instructions, open these files to view the documentation:

- HTML (multiple linked pages): open ``doc/build/html/index.html`` in a web browser
- PDF (single document): open ``doc/build/latex/pyrate.pdf`` in a PDF viewer
- Markdown (multiple linked pages, limited functionality): open ``doc/build/markdown/index.md``

.. code-block:: bash

    # install the extra Python dependencies
    pip install .[docs]

    # install the `dot` program to render inheritance diagrams (else they will appear as gibberish text)
    sudo apt install graphviz

    # change into the documentation directory
    cd doc

    # compile the docs into one or more of the below formats
    make html
    make latexpdf  # requires pdflatex
    make markdown

On Windows, `make.bat` can be used in place of `make` (untested, possibly requires installing additional dependencies).