===============
For Developers
===============

This section provides various hints for developers intending
to contribute towards the HermesPy code base.

Unit Testing
-------------

In order to minimize the chance of code-regressions with new contributions,
HermesPy implements various automated code testing routines.
New contributions are required to pass existing tests as well as provide
tests for additional features introduced with the contribution.

In order to launch unit tests locally,

.. code-block:: bash

    python -m unittest discover tests/unit_tests

can be executed from the project's root directory.
This will execute all unit tests located under `tests/unit_tests/`.
Additional tests for the integration of modules and the integrity of configuration files and examples
can be found under `tests/integration_tests/` and `tests/integrity_tests/`, respectively.
For asserting the unit test coverage, the Hermes pipeline deploys the `coverage`_ tool.
It can be executed by running the test script with the `coverage`_ command

.. code-block:: bash

    coverage run tests/test_install unit_tests

from the project's root directory.
The coverage report can be generated by running

.. code-block:: bash

    coverage report -m --include=hermespy/*

which will generate a list of all code statements not covered by the unit tests.
HermesPy is currently achieving a test coverage of 100% and kindly asks all contributors to maintain this level.

Type Checking
--------------------

HermesPy is written in Python 3.10 and fully type annotated.
The type annotations are checked by the `mypy`_ tool which can be executed by running by running

.. code-block:: bash

    mypy

from the project's root directory.

Coding Style
------------

Hermes enforces PEP8 compliant coding style, which can be tested by running `flake8`_

.. code-block:: bash

   flake8 hermespy/

from the repository root.
Most compliancy violations can be automatically resolved by running the `black`_ preprocessor

.. code-block:: bash

   black -C hermespy/

from the repository root.
Prior to their first execution, both tools must be manually installed in your environment of choice

.. code-block::

   pip install --upgrade flake8 black


Documentation
--------------

The documentation is generated by `Sphinx <https://www.sphinx-doc.org/>`_.
It requires some additional dependencies which may be installed from PyPi via

.. code-block:: bash

   pip install -e ".[documentation]"

The documentation source files are located under `/docssource/`, however,
most API information should be directly inserted into the source code files and inserted
by the `autodocs <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_
extension.
A reference example can be found in `/hermespy/simulation/rf_chain/power_amplifier.py`.
See :doc:`api/simulation/rf_chain.amplifier.PowerAmplifier` for the rendered results.

Sphinx with serveral extensions is used to generate the documentation.
Build the documentation by executing

.. code-block:: bash

   sphinx-build ./docssource/ ./documentation/

within the project's root directory.
This results in the rendering of a html-based documentation website,
located under `documentation/`.
In order to view it locally, open `index.html` within a web-browser of your choice.

.. _coverage: https://coverage.readthedocs.io/en/
.. _flake8: https://flake8.pycqa.org/en/
.. _black: https://black.readthedocs.io/en/
.. _mypy: https://mypy.readthedocs.io/en/