Contribution Guide

How to setup a development environment.

The following command will create a new development environment that contains all required and optional dependencies for the rt1_model package using the conda package-manager.

conda env create -f < path to rt1_dev.yml >

Click to view contents of rt1_dev.yml

name: rt1_dev
channels:
  - conda-forge
  - symengine

dependencies:
  # ---------- required dependencies
  - numpy
  - sympy
  - scipy

  # ---------- optional dependencies
  - matplotlib >=3.8
  - python-symengine

  # ---------- to run pre commits
  - pre-commit

  # ---------- for testing
  - pytest
  - pytest-cov
  - nbformat
  - cloudpickle

  # ---------- for building the docs
  - myst-nb
  - docutils
  - sphinx
  - sphinx-copybutton
  - sphinx-autobuild
  - sphinx-design
  - sphinx_rtd_theme
  - sphinxcontrib-bibtex

  # ---------- to run jupyter notebooks
  - jupyterlab
  - ipympl
  - pip
  - pip:
    - jupyterlab_myst # for MySt Markdown parsing in jupyterlab

When the environment is set up, make sure to activate it using

conda activate rt1_dev

Now its time to install the rt1_model package in editable mode!

To do so, first clone the GitHub repository, then navigate to the parent directory (containing the pyproject.toml file) and execute the following command:

pip install -e .

That’s it! You’re all set!

Once you’re done with coding, head over to GitHub, and open a new Pull Request to start discussions and get help!

Code formatting

The rt1_model package uses the black code-style and pre-commits to ensure code-formatting for changes pushed to GitHub.

To initialize pre-commits, execute the following command (again in the parent-directory containing the .pre-commit-config.yaml file.

pre-commit install

Now pre-commit is run prior to pushing commits to GitHub and black code-formatting is applied to all staged files.

You can also manually run pre-commit on all files by executing:

pre-commit run --all-files

Note

You must stage all changes performed by the automatic re-formatting prior to pushing to GitHub!

Building the docs

The documentation for the rt1_model package is built with sphinx and hosted on readthedocs.

To build the docs locally, navigate to the docs subfolder (containing the source-files for the docs and a make.bat file) and run the following command:

make html

This will create the following subfolders:

• docs\build which contains the compiled html source of the documentation.

• docs\generated which contains the auto-generated API docs (parsed from the python code) created by sphinx-autodoc.

• docs\jupyter_execute and docs\.jupyter_cache which contain the (cached) executed jupyter-notebook examples created by myst_nb.

Once the process is finished, you can view the created docs by opening the start-page: docs\build\html\index.hml.

It is also possible to start a local http server and automatically update the docs on source-changes using sphinx-autobuild. To use it, first make sure it is properly installed, then navigate to the docs directory and execute:

sphinx-autobuild . build

This will start a new local http-server showing the docs (by default at localhost:8000) and updated files are automatically re-compiled and re-loaded if a change in the source-files is detected.