Contribute¶
This document will guide you through the necessary setup and conventions on order to contribute to this project.
Jupyter notebook conventions¶
The versioning of Jupyter Notebooks is not the greatest as for example the execution count of each cell is stored in the notebook. We will use an automatic tool called pre-commit to clean the notebook of any unnecessary content (see pre-commit).
Also storing binary blobs such as images can lead to a big repository soon - so if we decide to include such blobs it is best to make the generation of these as stateless as possible. To achieve this one can use tools such as setting the random seed to make any randomness deterministic.
pre-commit¶
pre-commit allows us to run certain checks before a commit is made,
so much like git hooks
but configurable through a .pre-commit-config.yaml file.
This gives us the ability to e.g. clean the notebooks of the execution count of each cell as this can lead to lot of noise in the VCS.
pre-commit is already installed as a dependency (see Installing dependencies), but in order to activate it we need to install the necessary hooks to our git repository by running
pre-commit install
After this just use your normal git workflow - keep in mind that pre-commit can prevent you from committing files because pre-commit found an issue with them - most often pre-commit will automatically try to fix the issue and you need to stage this changes to your commit after which the commit should work without issues.
Building the documentation¶
In order to build the documentation locally one also needs to install the dependencies of the documentation by executing the following command in the root directory of the repository (see Repository setup) and activating the virtual environment (see Activating the virtual environment).
pip3 install -r requirements-docs.txt
After this the documentation can be build by executing the shell script
./build_docs.sh
from the root directory of the repository.
Convention
If you want to open the documentation in a browser after it has been build you can set the environment variable
export OPEN_BROWSER_AFTER_TEST=true
when using the ./build_docs.sh script.
Remember that this has to be set every time you open a shell or you add it to your ~/.zshrc or else.