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), clone it, and then add an upstream repository.

    More information on: GitLab doc: forking workflow.

    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.

    $ # 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
2. Develop your contribution:

Pull the latest changes from upstream:

$ 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).

$ 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.

3. Submit your contribution:

Push your changes to your fork:

$ 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 Setting up a virtual environment of the installation process.

Then see the chapter Install the development version.

Documentation

Documentation is built using Sphinx and hosted cadbiom.genouest.org.

Documentation is mostly written as reStructuredText (.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:

Human-readable command-line documentation is written using a Sphinx extension called sphinx-argparse.

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:

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:

make -C ./doc clean

Report bugs

Please report bugs on GitLab.