Contributing to GBSpy
=====================

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

.. contents::
   :depth: 2

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 <https://c4science.ch/project/board/3515/>`_.

Working with the code
---------------------

The development of gbspy is conducted using the Git version control system.
Although `download options <https://git-scm.com/downloads>`_ are offered, most
UNIX systems already ship with an installation of ``git``. If you've never
worked with Git before, the
`git tutorial <https://git-scm.com/docs/gittutorial>`_
should guide you through the basics.
The gbspy repository is stored on `c4science <https://c4science.ch/>`_, on
which you will need an account before cloning the code. Refer to their
`wiki <https://c4science.ch/w/c4science/>`_ to configure your client and
account.

Guidelines on the development workflow can be found in the
`GBS documentation <https://gbs.epfl.ch/git_workflow.html>`_.

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 <https://www.sphinx-doc.org/>`_
documentation engine, which is based on reStructuredText. A good starting point
to writing reST is found on the
`Sphinx website <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
We also host an :doc:`example <example_page>` illustrating the basics.

Documentation of Python objects, such as classes and functions, can be largely
automated thanks to Sphinx's
`apidoc <https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html>`_.
To this end, documentation strings (docstrings) are included in the Python
source files and follow a particular syntax: the
`Numpy Docstring Standard <https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard>`_,
for which we also include a :doc:`summary <document_code>`.

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 <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`_.
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,

.. code-block:: bash

   # 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

.. code-block:: bash

   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 <https://gbs.epfl.ch/git_workflow.html>`_
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 <https://pre-commit.com/>`_ with this repository. In
particular, these hooks enforce the
`Black style <https://black.readthedocs.io/en/stable/>`_, sort the imports
using `isort <https://pycqa.github.io/isort/>`_ and run
`flake8 <https://flake8.pycqa.org/en/latest/>`_.

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(+)