Continuous Integration
----------------------

Continuous integration is an essential part of the software's development workflow,
allowing the automation of multiple steps including code compilation, testing and deployment.
This package utilizes several popular CI platforms to perform continuous integration: GitHub Actions and Travis-CI.

.. contents::
   :depth: 2
   :local:


Unit tests
==========

Our unit tests are written compatible with `pytest <https://docs.pytest.org/en/stable/>`_ module, which
provides straightforward test execution and error reporting as well as an easy solution to assess test
coverage.
``pytest`` follows the standard test discovery rules that can be found
`here <https://docs.pytest.org/en/stable/goodpractices.html#conventions-for-python-test-discovery>_`.
For simple tests, we just need to write some functions with prefix ``test``, while it is also possible
to write test classes with prefix ``Test``.
Additionally, ``pytest`` also provides a variety of features including fixtures and parameterization to
facilitate unit testing.


CI Configuration for GitHub Actions
===================================

GitHub Actions is a continuous integration platform provided by GitHub with a variety of community built ``action``,
that can be easily used to execute tasks with minimum configuration.
For example, with our unit testing workflow, we uses the ``actions/checkout@v2`` action to check out the repositories,
the ``actions/setup-python@v2`` to setup python of a specific version. 

At the moment we implemented 2 types of workflow to perform unit tests and deploy the package.

Unit Testing Workflow
+++++++++++++++++++++

In the unit testing workflow, our goal is to compile and unit test our package on both ``ubuntu`` and ``macos`` operating systems,
with both Python 3.8 and 3.9versions. The workflow is executed whenever a branch recieves a push or a pull request (excluding branches with prefix ``text``),
and the workflow can also be triggered manually for testing purposes.

The workflow consits of the following steps:

#. Check out the package repository with ``actions/checkout@v2`` action and install python of the specified version with ``actions/setup-python@v2`` action;
#. Installed build and runtime dependencies using ``apt``/``brew`` and ``pip``;
#. Compile and install the package;
#. Check out the unit test repository with ``actions/checkout@v2`` action;
#. Install test dependencies with ``pip``;
#. Run unit tests with ``py.test`` and assess test coverage with ``coverage``.

.. literalinclude:: _static/ci-workflows/python-package.yml
   :caption: python-package.yml
   :language: yaml


Deployment Workflow
++++++++++++++++++++++

The goal of the deployment workflow is the build the package and its extensions into python wheels for a variety of platforms for easy distribution.
This is usually a very cumbersome task.
However, with the cibuildwheel package and the ``pypa/cibuildwheel@v2.2.2`` action provided by Python Packaging Authority (PyPA).
The wheels for a variety of platforms and python versions can be built with only a few lines of configuration.

.. literalinclude:: _static/ci-workflows/github-deploy.yml
   :caption: github-deploy.yml
   :language: yaml


CI Configuration for Travis-CI
==============================

Here we demonstrate the Configuration of CI workflow on Travis-CI of the package:


1. Set up the environment. Since the package mainly uses Python, the environment is fairly easy to setup.
   Folowing is an exmple for Travis-CI, that configures an linux environment with a matrix of 2 Python version: 3.8 and 3.9.

.. code-block:: yaml

    language: python

    os:
      - linux

    cache: pip

    virtualenv:
      system_site_packages: false

    python:
      - "3.8"
      - "3.9"

2. The next step is to install dependencies.
   Both dependencies for the extensions and the required Python libraries will be installed in this step.

.. code-block:: yaml

    # command to install dependencies
    before_install:
      - sudo apt-get update
      - sudo apt-get install -y gcc libopenblas-dev libgomp1 make
      - python -m pip install --ignore-installed -r requirements.txt


3. Then the package needs to be compiled and installed, in order to be tested.

.. code-block:: yaml

    # command to compile and install code
    install: |
      echo "Build Package"
      python setup.py build
      python setup.py install


4. After the package is successfully installed, the unit tests need to be checked out and executed.
   Tests coverage will be assessed in the meantime.

.. code-block:: yaml

    # command to run tests
    script: |
      echo "Test package"
      git clone git@github.com:marianettigroup/principia-materia-tests.git
      cd principia-materia-tests
      python -m pip install coverage-badge
      python -m pip install -r requirements.txt
      cd tests && make

5. After the tests are successfully executed, one can compute the coverage statistics
   and generate coverage report and coverage badge.
   Meanwhile it can also be setup in a way when a new release is pushed to the git repository,
   the code will be compiled, packaged and uploaded to software repository platforms.

.. code-block:: yaml

    # command to create coverate report and badge
    after_success: |
      cd ${TRAVIS_BUILD_DIR}/principia-materia-tests/tests
      coverage xml
      coverage html
      coverage-badge -o coverage.svg


CI for Documentation
====================

The documentation website of the package is hosted with GitHub Pages and is built and deployed conveniently using GitHub Action.
The build process is similar to a regular python package with running ``sphinx-build`` command at the end.
The ``peaceiris/actions-gh-pages@v3`` action is used to deploy the built website to the ``gh-pages`` branch of the ``marianettigroup/marianettigroup.github.io``
repository, making it accessible from the URL `marianettigroup.github.io <https://marianettigroup.github.io>`_.

.. literalinclude:: .github/workflows/sphinx-docs.yml
   :language: yaml