Developer Guide

This section includes information for developers who want to contribute to the project. It includes information about the project structure, how to run the tests, and how to build the documentation. It also includes information about the project’s coding style and how to contribute to the project.

Coding Guidelines

The project follows the PEP8 coding style. The project uses setuptools for packaging and distribution. The project uses Sphinx for documentation. The project uses pytest for testing. The project uses Gitflow for branching.

In order to contribute to the project, it is important to follow the coding style and guidelines used by the project, therefore please read ALL of the following sections carefully.

How to Contribute

For any contributor willing to contribute to the project, it is important to understand the branching model used by the project. The project uses the Gitflow branching model. In order to contribute to the project please follow the following steps:

1. Fork the project on Github. (not necessary if you are a member of the project)

2. Clone your fork locally:

   $ git clone https://github.com/MolarVerse/PQAnalysis.git
   

3. Initialize git flow with the following settings (if not specified default settings are used)

   [master] main
   [develop] dev
   [version tag prefix] v
   

4. Create a feature branch for your contribution:

   $ git flow feature start <feature_branch_name>
   

5. Commit your changes to your feature branch and publish your feature branch:

   $ git add <files>
   $ git commit -m "commit message"
   $ git flow feature publish <feature_branch_name>
   

6. Create a pull request on Github.

7. Once your pull request is approved, it will be merged into the develop branch.

Documentation

Please make sure that all code is well documented. The project uses Sphinx for documentation. The documentation of this webpage is autogenerated from the docstrings of the implemented code, thus it is important to make sure that all docstrings are correct and informative.

Attention

The project uses numpydoc for docstring formatting. Please make sure that all docstrings are formatted correctly.

In order to install all the dependencies required for building the documentation, use the following command:

$ pip install .[doc] # install the project with the documentation dependencies

To build the documentation, use the following command:

$ cd docs

$ make html

In order to view the documentation, open the following file in a web browser:

$ open build/html/index.html

For the CI/CD pipeline, the a documentation coverage of 99.9% is required. Please make sure that all implemented features are correctly documented. To evaluate the documentation coverage, use the following command:

$ docstr-coverage PQAnalysis

Testing

The project uses pytest for testing. Before creating a pull request, please make sure that all tests pass and ensure a high quality of code coverage. In order to run the tests, use the following command:

$ pip install .[test] # install the project with the test dependencies

$ python -m pytest

The testing framework will run all tests and provide automatically generated coverage reports. Not only should all tests pass, but the coverage should be as close to 100% as possible. Furthermore, the project automatically uses doctest, so please make sure that all examples included in the doc strings of the implemented features are correct otherwise the tests will fail.

Last, if any additional dependencies are required for testing, please add them to the pyproject.toml file under the [project.optional-dependencies] section.