CONTRIBUTING.md

Contribution guidelines

• Jupyter-book supports multiple content types. Their flavour of Markdown is preferred.
• Please start each sentence on a new line in the documentation. This allows for better diffs and pull requests.

Building docs locally

The documentation currently uses Jupyter-book. To build the documentation locally, to test before opening Pull Requests for example, a virtual environment can be used:

  # Create a new virtual environment
  $ python3 -m venv ./.venv
  # Activate the virtual environment
  $ source .venv/bin/activate
  # Install the necessary Python packages
  $ pip install -r requirements-book.txt
  # Build the docs
  $ jupyter-book build ./source
  # This will create the HTML files in ./source/_build/html

To deactivate the virtual environment:

  $ deactivate

More information on Python virtual environments can be found in the Python documentation here.

Publishing the book

The book is published using GitHub pages, using the ghp-import tool.

  # Use ghp-import
  $ ghp-import -n -p -f ./source/_build/html

This will import the HTML files built by jupyter-book to the gh-pages branch. More information on this can be found in the official documentation.

A helper script ./build-helper.sh is present in the repository to assist with these steps.