Writing tutorials#

Setup#

First, setup your environment according to the Setup instructions.

Installing extra dependencies#

Now, activate your environment:

conda activate {env-name}

And run the following:

pip install jupyterlab jupytext

Start JupyterLab with:

jupyter lab

Once JupyterLab starts, you’ll see the file navigator on the left. Tutorials are always located in the doc/ directory:

files

To automatically reload your changes to the code in an existing notebook, run this before any import statements:

%load_ext autoreload
%autoreload 2

This way, you don’t have to restart the kernel with every change. Note that this approach has some quirks, you might need to restart the kernel in some situations.

Editing an existing notebook#

We store the notebooks in .md format; however, you can open them as notebooks:

files

Creating a new notebook#

To create a new tutorial, create a new Markdown document:

files

Then double click on it and add this at the top (do not leave any empty lines):

---
jupytext:
  notebook_metadata_filter: myst
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.14.4
kernelspec:
  display_name: Python 3 (ipykernel)
  language: python
  name: python3
---

Then, close the file and open it as a notebook as shown in the Editing an existing notebook section.

Important

Remember to add your notebook to doc/_toc.yml to ensure it’s included in the documentation.

Tip

Before writing a tutorial, go over the checklist.