Setup the local copy of the code¶
If you are a new contributor, you have to fork the repository (https://gitlab.inria.fr/pvignet/cadbiom), clone it, and then add an upstream repository.
More information on: GitLab doc: forking workflow.
Please note that the currently (2017-2020) active branch of development is named
masterbranch is the stable release branch; please avoid proposing pull-requests on this branch except for bugfixes.
$ # Clone your fork $ git clone -b pypi_packaging email@example.com:<your_username>/cadbiom.git $ # Add upstream repository $ git remote add upstream firstname.lastname@example.org:pvignet/cadbiom.git
Now, you should have 2 remote repositories named (
- upstream, which refers to the Cadbiom repository
- origin, which refers to your personal fork
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 (
Cover your code with unit tests and run them before submitting 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 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.
The documentation source-files are located in
./doc/source/index.rst being the main entry point.
Each subsection of the documentation is a
.rst file inside
Html files are generated in
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