How to add a new mixing method to Taweret
=========================================

Taweret is meant to be extensible and is willing to accept any mixing methods the community develops.
These notes serve as instructions on how you can add your mixing methods to the Taweret repository.
All mixing methods in Taweret must inherit from the base class in ``Taweret/core``.
To add a new mixing method (or model), you need to:

- Step 1: Fork the repository, and clone it

.. code-block:: bash

   git clone <your fork>

- Step 2: Navigate to the ``Taweret/mix`` directory and open a file to contain your new mixing method. Sans any comments you wish to add, the first several lines should look like

.. code-block:: python

    from Taweret.core.base_mixer import BaseMixer

    class MyMixer(BaseMixer):
        def __init__(self, ...):
            ...

The ``BaseMixer`` is an abstract base class which has certain methods that need to be defined for its interpretation by the Python interpreter to succeed. These methods, and their descriptions, can be found in the API documentation for the ``BaseMixer``

- Step 3: Add unit tests for mixing method to the the pytest directory. To make sure the python interpreter sees the added modules, the first several lines of your test file should read

.. code-block:: python

   import os
   import sys

   dirname = __file__
   taweret_wd = dirname.split('test')[0]
   sys.path.append(taweret_wd)

   from Taweret.mix.<your_module> import *
   import pytest

   # All functions starting with `test_` will be registered by pytest

- Step 4: You need to document your code well, following the examples you see in existing mixing methods, which includes type annotations and RST style code comments. The documentation generations should automatically identify your code

- Step 5: Clean your code using the output of the ``flake8`` style guide tool.  See the ``check`` tox task for one possible means to do this.

- Step 6: Create a pull request of your addition into the `develop` branch. This should trigger a GitHub action. Should the action fail, please try to diagnose
  the failure. Always make sure the tests execute successfully locally before opening a pull request