.. _notes_for_developers:

====================
Notes for developers
====================

Make sure to work in a suitable virtual environment. See :ref:`use_venv`
for more information.


Running tests
-------------

ViPErLEED comes with a suite of tests and uses
`pytest <https://docs.pytest.org/en/>`__ for testing.
The :term:`TensErLEED` source code should be available on the testing machine
(repository ``viperleed-tensorleed``) and the ``VIPERLEED_TENSORLEED``
:term:`environment variable` should be set. See also :ref:`install_tensorleed`.

Also make sure to have compiled the :ref:`eeasisss_compile` source code.

ViPErLEED should also be installed with optional development dependencies as

.. code-block:: bash

    python -m pip install viperleed[dev]

To execute tests, navigate to your local copy of the ViPErLEED
`repository <https://github.com/viperleed/viperleed>`__,
then run

.. code-block:: bash

    python -m pytest .

If you also would like to produce coverage reports, install :program:`coverage`
via

.. code-block:: bash

    python -m pip install coverage

then, in your local copy of the ``viperleed`` repository, run

.. code-block:: bash

    python -m coverage run -m pytest .
    python -m coverage html



Using editable installations
----------------------------

ViPErLEED is installed from source using the code in the ViPErLEED
`GitHub repository <https://github.com/viperleed/viperleed>`__. It
uses the :file:`pyproject.toml` file. To install an
`editable version <https://setuptools.pypa.io/en/latest/userguide/development_mode.html>`__,
navigate to your copy of the :file:`viperleed` repository, and use

.. code-block:: bash

    python -m pip install -e .[<options>]

Editable installations from :file:`pyproject.toml` files
require ``pip>=21.3``. Update your ``pip`` with

.. code-block:: bash

    python -m pip install --upgrade pip


Building this documentation
---------------------------

Install ViPErLEED from source using the code in the ViPErLEED
`GitHub repository <https://github.com/viperleed/viperleed>`__
including the documentation dependencies by running

.. code-block:: bash

    python -m pip install .[doc]

in your local copy of the :file:`viperleed` repository. Note that
the documentation can only be built with :program:`Python` ≥3.9 because of
dependency-resolution issues.

Navigate to the :file:`doc` subfolder of :file:`viperleed`, then

.. tab-set::

    .. tab-item:: Linux, macOS, WSL

        .. code-block:: bash

            make html

        or

        .. code-block:: bash

            make latexpdf


    .. tab-item:: Windows

        .. code-block:: bat

            make.bat html

        or

        .. code-block:: bash

            make.bat latexpdf

Producing the PDF documentation requires a working LaTeX
installation on your system.