Contribute to the project

Any problem or a question

If you have an issue or a question about the project, you may open an issue on the gitlab:

https://gitlab.lre.epita.fr/olena/pylena/-/issues

Contribute to the software

To submit a patch or a new feature, you have to:

  1. Create a user account on https://gitlab.lre.epita.fr

  2. Fork the project

  3. Create a merge request

The created git branch should have as source branch the next branch and merge destination branch the same. This repository respects the following convention for branches:

  • master is the production branch. The resulting built wheel and source distribution are pushed to PyPI.

  • next is the unstable branch. The resulting built wheel are pushed in an internal gitlab package index, compatible with pip.

  • The other branches, named development/*feature*, where feature is a short name for the feature developed, are development branch and should origin from next and have a destination to next.

Contribute to the code

This project aims to expose C++ functionalities from Pylene to Python. To do that, it uses the Pybind11 library. These C++ dependencies are handled thanks to Conan and the build step is made using CMake.

To build the bindings, the developer just have to execute the following at the root of the project:

$ python setup.py build_ext --inplace

This build the library exposing the C++ functionalities. When you want to make a wheel the project, you just have to do following step in the project root:

$ python -m pip install build # First time
$ python -m build

It will produce a wheel and a source distribution in the dist/ directory generated at the root of the project.

When writing code in this project, please use the formatters available (clang-format for C++ code and the Ruff Formatter for Python code).

The API is written in the following way: first, the C++ functionalities are exposed in Python using pybind11. The produced Python module is named pylena_cxx. Then, its features are wrapped in Python, to make it more Python user-friendly. Some type checking can be made using the Python decorators such as pylena.check_type() and pylena.check_numpy_array(). Furthermore, the usage of type hints is mandatory for exposed features. Each exposed feature should be imported in the corresponding __init__.py and added in the __all__ list of this file.

Each new functionality should have tests, a correct documentation in the API reference and an example showing how to use it. These steps are described in the following subsections.

Contribute to the documentation

The documentation is divided into two parts:

  • The sphinx part, in /doc/source, which contains the configuration file and the rst pages of the documentation.

  • The examples part, in /doc/examples, which contains python files with the executed examples.

To generate the documentation, build a wheel (as explained above) and run the following from the project root:

$ python -m pip install /path/to/your/wheel.whl[doc] # Will install pylena and the documentation requirements
$ mkdir build && cd build
$ python -m sphinx -b html ../doc/source ./sphinx

It will generate the documentation in HTML format.

The documentation is written using rst files. For the API Reference section, the documentation is generated using the docstrings in the python files. The docstring are written in the NumPy docstring standard.

The generation of the API reference is not (yet) generated automatically. However, the docstring are parsed thanks to sphinx autodoc and sphinx napoleon. So when writing a new functionality, do not forget to add the autodoc directives to the documentation.

The examples are generated thanks to Sphinx Gallery. These are composed of python script which will be executed and automatically converted into html files. The text in these files can be written in rst, which make possible to structure well these example as well as write simple python script. Futhermore, Matplotlib is entirely handled by Sphinx Gallery, which makes easy to plot images and more.

Note that all documented image processing algorithm should have at least one reference to an article

Contribute to the tests

The tests, located in the /tests directory, are written using the pytest library. To use them, execute the following:

$ python -m pip install /path/to/your/wheel.whl[tests] # Will install pylena and the tests requirements
$ cd tests # Be sure to not be in the project root dir as it would be appended to your python path
$ python -m pytest

Each functionalities should be tested. To improve the quality of the testing, some code coverage is performed in the merge request process and in case of push in the principal branches.