Developer overview
==================

Setup the local copy of the code
--------------------------------

1. If you are a new contributor, you have to fork the repository
   (`https://gitlab.inria.fr/DYLISS/cadbiom <https://gitlab.inria.fr/DYLISS/cadbiom>`_), clone it,
   and then add an upstream repository.

   More information on: `GitLab doc: forking workflow <https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html>`_.

   .. note::
      Please note that the currently (2017-2020) active branch of development is named ``pypi_packaging``.
      The ``master`` branch is the stable release branch; please avoid proposing pull-requests on this branch except for bugfixes.


   .. code-block:: bash

      $ # Clone your fork
      $ git clone -b pypi_packaging git@gitlab.inria.fr:<your_username>/cadbiom.git
      $ # Add upstream repository
      $ git remote add upstream git@gitlab.inria.fr:pvignet/cadbiom.git


   Now, you should have 2 remote repositories named (``git branch``):

   - upstream, which refers to the Cadbiom repository
   - origin, which refers to your personal fork

.. new line

| 2. Develop your contribution:

   Pull the latest changes from upstream:

   .. code-block:: bash

      $ git checkout <branch_of_reference>
      $ git pull upstream <branch_of_reference>

   Create a branch for the feature you want to work on; the branch name should be explicit and if possible related to an
   opened issue (Ex: Issue number *000* in the following).

   .. code-block:: bash

      $ git checkout -b bugfix-#000

   **Make small commits with explicit messages about why you do things as you progress** (``git add`` and ``git commit``).

   **Cover your code with unit tests and run them before submitting your contribution.**

.. new line

| 3. Submit your contribution:

   Push your changes to your fork:

   .. code-block:: bash

      $ git push origin bugfix-#000

   Go to the GitLab website. The new branch and a green pull-request button should appear.
   To facilitate reviewing and approval, it is strongly encouraged to add a full description of
   your changes to the pull-request.


Build environment setup
-----------------------

Once you’ve cloned your fork of the Cadbiom repository, you should set up a Python development environment tailored for Cadbiom.

See the chapter :ref:`setting_up_a_virtual_environment` of the installation process.

Then see the chapter :ref:`install_dev_version`.


Documentation
-------------

Documentation is built using `Sphinx <http://sphinx-doc.org/>`_ and hosted `cadbiom.genouest.org <http://cadbiom.genouest.org/doc/cadbiom>`_.

Documentation is mostly written as `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
(.rst) files, but they can also be Markdown (.md) files. There are advantages to both formats:

- reStructuredText enables python-generated text to fill your documentation as in the auto-importing
  of modules or usage of plugins like `sphinx-argparse`.
- Markdown is more intuitive to write and is widely used outside of python development.
  If you don't need autogeneration of help documentaiton, then you may want to stick with writing Markdown.


Here's a subset of reStructuredText to help you get started writing these files:

- `Full specification <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`_
- `Quick references for Sphinx <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`_

Human-readable command-line documentation is written using a Sphinx extension called
`sphinx-argparse <https://sphinx-argparse.readthedocs.io/en/latest/index.html>`_.


Folder structure
~~~~~~~~~~~~~~~~

The documentation source-files are located in ``./doc/source/``, with ``./doc/source/index.rst`` being the main entry point.
Each subsection of the documentation is a ``.rst`` file inside ``./doc/source/``.

Html files are generated in ``./doc/build/``.


Building documentation
~~~~~~~~~~~~~~~~~~~~~~

Building the documentation locally is useful to test changes.
First, make sure you have the development dependencies installed; See `Build environment setup`_

Then build the HTML output format by running:

.. code-block:: bash

    make doc
    # or
    make -C ./doc html


Sphinx caches built documentation by default, which is generally great, but can cause the sidebar
of pages to be stale. You can clean out the cache with:

.. code-block:: bash

    make -C ./doc clean


Report bugs
-----------

Please `report bugs on GitLab <https://gitlab.inria.fr/DYLISS/cadbiom/issues>`_.