Developing

Documentation is inspired from WhatsHap

Developer’s Installation

For installation gaftools for the purpose of development, please use a conda environment.

Conda environment can be used using these commands:

git clone git@github.com:marschall-lab/gaftools.git
cd gaftools
conda create -n gaftools-dev python=3.10
conda activate gaftools-dev
pip install -e .[dev]

Adding a new subcommand

For creating a new subcommand under gaftools, add a new script under gaftools/cli/. Make sure to follow the same format and add test cases for the subcommand under tests.

Since gaftools is purely written in Python, adding a script is enough. If the new script adds external dependencies, then add the dependencies to requirements.txt.

Executing Test Cases

To execute all the tests (collected in tests) run:

pytest

To generate an html report on the test coverage:

coverage run -m pytest
coverage report -m
coverage html
firefox  htmlcov/index.html

To format using ruff, run:

ruff format gaftools/ tests/ setup.py

To check for syntax and style errors using ruff, run:

ruff check gaftools/ tests/ setup.py

To check for proper documentation build, proper syntax and styling, and pytest on multiple python versions (installed locally), run:

tox

Before creating a pull request

write test cases for the new code
run tox after fixing formatting and syntax with ruff
create the pull request, if the tox check passes with your local python version

Using Pre-Commit

The tox pipeline has been integrated into GitHub as a CI/CD pipeline. Instead of doing all the checks locally, the checks can be done online.

There is also pre-commit support which also allows developers to skip the formatting and syntax checking using ruff.

To install pre-commit, run:

pip install pre-commit
cd <directory of git repository>
pre-commit install

Now you pre-commit will run everytime you commit to the repository. But the pre-commit run is restricted to the staged files. As an optional step, you can run pre-commit on all the file using:

pre-commit run --all-files

When the staged files fail the conditions defined in the pre-commit conditions, ruff formatting will attempt to fix it. After adding the files updated by ruff, attempt to commit again. If it fails, then the errors have to be manually fixed.

Writing Documentation

The documentation for gaftools is written in reStructuredText format and is translated by Sphinx into HTML format. The documentation is found under docs

The documentation is hosted on Read the Docs.

For testing the documentation, run developers installation and under docs, run make html. This creates the htmls for the files under _build.

Adding C++ and Cython scripts

Currently, the setup script does not support building of C++ scripts and wrapping them into Python using Cython. If it is required for any future work, refer to the WhatsHap setup structure and its documentation to add C++ and Cython scripts.

Accordingly this documentation for developing will have to be changed.

Making a Release

Update CHANGES.rst: Set the correct version number and ensure that all nontrivial, user-visible changes are listed.
Ensure you have no uncommitted changes in the working copy.
Run tox.
Tag the current commit with the version number (there must be a v prefix):
```
git tag -a -m "Version 0.1" v0.1
```
Push the tag:
```
git push --tags
```
Wait for the GitHub Action to finish. It will deploy the sdist and wheels to PyPI if everything worked correctly.

If something went wrong, fix the problem and follow the above instructions again, but with an incremented revision in the version number. That is, go from version x.y to x.y.1. PyPI will not allow you to change a version that has already been uploaded.