Contributing to GBSpy

Contributions to the code and documentation are always welcome, whether to improve the existing code, add new features or fix bugs.

Bug reports and feature requests

If you think you found a bug, encountered undesirable behavior or found a possible addition to gbspy, we encourage you open an issue on the dedicated c4science workboard.

Working with the code

The development of gbspy is conducted using the Git version control system. Although download options are offered, most UNIX systems already ship with an installation of git. If you’ve never worked with Git before, the git tutorial should guide you through the basics. The gbspy repository is stored on c4science, on which you will need an account before cloning the code. Refer to their wiki to configure your client and account.

Guidelines on the development workflow can be found in the GBS documentation.

Working with the documentation

Along with developing the code, maintaining the documentation is an important step towards engaging new users and making the toolbox easy to work with. Note that even as a non-developper, contributions to the documentation are welcome.

The documentation is built by the Sphinx documentation engine, which is based on reStructuredText. A good starting point to writing reST is found on the Sphinx website. We also host an example illustrating the basics.

Documentation of Python objects, such as classes and functions, can be largely automated thanks to Sphinx’s apidoc. To this end, documentation strings (docstrings) are included in the Python source files and follow a particular syntax: the Numpy Docstring Standard, for which we also include a summary.

To generate the documentation locally, you will need additional dependencies compared to the main package, in particular Sphinx itself and the Sphinx Read The Docs theme. Depending on your installation method, you can either install the conda environment found in conda_environments/docs.yml or install the "docs" extras (through pip or a similar tool). Assuming the current working directory to be at the root of the git repository,

# To install the conda environment:
conda env create -f conda_environments/docs.yml

# To install the "extra requires" with pip
pip install ".[docs]"

Once these dependencies have been installed, you should be able to generate a local copy of the documentation by running

cd docs
make api  # builds the API in source/api
make html  # builds the HTML docs in build/html

# You should now be able to open the documentation, e.g.
firefox build/html/index.html

It is also recommended to use a proper git workflow when editing the documentation.

Warning

The documentation hosted online is generated automatically from the master branch. It is thus strongly recommended modifications to be done in a separate branch at first, and merged back in master after building the documentation locally and checking that no errors arise.

Code standards

Although no formatting standard is enforced, we package pre-commit hooks with this repository. In particular, these hooks enforce the Black style, sort the imports using isort and run flake8.

Once installed with pre-commit install, these hooks will be executed when running git commit, leaving an output which might ressemble the following,

$ git commit -m "Add super awesome feature"
black....................................................................Passed
Trim Trailing Whitespace.................................................Passed
Fix End of Files.........................................................Passed
Check Yaml...........................................(no files to check)Skipped
Debug Statements (Python)................................................Passed
Flake8...................................................................Passed
Reorder python imports...................................................Passed
rst ``code`` is two backticks........................(no files to check)Skipped
rst..................................................(no files to check)Skipped
changelog filenames..................................(no files to check)Skipped
[master 146c6c2c] Add super awesome feature
 1 file changed, 1 insertion(+)