94 lines
3.9 KiB
ReStructuredText
94 lines
3.9 KiB
ReStructuredText
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).
|