.. |major| replace:: 3
.. |minor| replace:: 3
.. |point| replace:: 0
.. |major_minor| replace:: \ |major|\ .\ |minor|\ 
.. |blender_major_minor| replace:: blender-\ |major|\ .\ |minor|\ .\ |point|\
.. |python_minor| replace:: 10

Contributing
============

Requirements
------------

Install `Poetry <https://python-poetry.org/docs/#installation>`_.
Poetry is used to manage dependencies and so called Poetry shells, which are essentially virtual environments.

Make sure you have ``git`` and ``make``.

.. code-block:: bash
    :caption: Debian and Ubuntu (and derivatives)

    sudo apt install git make



Getting the source code
-----------------------

Generate an SSH key pair following the instructions from
`<https://docs.gitlab.com/ee/ssh/#rsa-ssh-keys>`_.

Clone the repository into your favourite directory using:

.. code-block:: bash

    git clone git@gitlab.discretization.de:pyddg/pyddg.git

This will create a directory ``pyddg``.

To push local changes on git don't forget to tell git who you are by running

.. code-block:: bash

    git config --global user.email "you@example.com"
    git config --global user.name "Your Name"



Installing the library and Blender
----------------------------------

.. warning::
    Don't install Blender using other methods unless you know what you are doing.
    The ``setup_blender`` script ensures that Blender can use virtual environments.
    For more details, consult the `Blender documentation <https://docs.blender.org/api/current/info_tips_and_tricks.html#bundled-python-extensions>`_ and the ``setup_blender`` source code.

Install Blender

.. parsed-literal::

    # Install Blender |major_minor|.\ |point| \ to ~/blender
    scripts/setup_blender ~/blender |major| |minor| |point|

.. warning::
    Blender is expected to crash if you attempt to run it now.
    Blender won't work until you enter the Poetry shell or virtual environment and set certain environment variables as described below.

Then run

.. parsed-literal::
   
    cd pyddg    # the project directory
    poetry env use ~/blender/\ |blender_major_minor|\ /\ |major_minor|\ /_python/bin/python3.\ |python_minor|
    poetry install --with dev --with docs --with tests --with coverage

Enter the virtual environment with

.. parsed-literal::

    # poetry
    export PATH="$HOME/blender/\ |blender_major_minor|\ :$PATH"
    export PYTHONPATH="$(poetry env info -p)/lib/python3.\ |python_minor|\ /site-packages/"
    poetry shell

Run tests with

.. code-block:: bash

    python3 test.py

You can run tests selectively.
For all options, consult

.. code-block:: bash

    python3 test.py --help

Build documentation with

.. code-block:: bash
    :caption: Linux and macOS

    make -C docs/ docs

.. code-block:: doscon
    :caption: Windows

    docs\make.bat docs

and open ``docs/build/index.html`` in your favorite browser.

Clean the build artifacts with

.. code-block:: bash
    :caption: Linux and macOS

    make -C docs/ clean

.. code-block:: doscon
    :caption: Windows

    docs\make.bat clean

Exit the Poetry shell with

.. code-block:: bash

    exit