Add Jupyter notebooks to documentation#

This documentation is to help you get started with adding Jupyter notebooks to your documentation. The notebooks can be static or dynamic and interactive with Binder.

Quick-start#

Create Jupyter notebook (https://jupyterlab.readthedocs.io/en/stable/getting_started/overview.html)
Include ipykernel and nbsphinx in requirements.txt (/docs) and update conf.py with nbsphinx. For more information, see https://nbsphinx.readthedocs.io/en/0.9.3/
Add files to GitHub documentation repository (/docs/tutorials)

Static notebooks#

Static notebooks within the documentation will render as html. To do this you need to create a notebook, update requirements.txt file, and then add the notebook and files to the github repository for the documentation.

Create notebook#

Use the following steps for creating a static notebook:

Install JupyterLab, type the following in command prompt or terminal:
```
pip install jupyterlab
```
Start JupyterLab, type the following in command prompt or terminal
```
jupyter lab
```
Create notebook(s), see https://jupyterlab.readthedocs.io/en/latest/user/notebook.html

Note

You can use VS Code instead of JupyterLab, see https://code.visualstudio.com/docs/datascience/jupyter-notebooks

Update requirements.txt#

In addition to the packages included in the requirements.txt file in the /docs folder for building the documentation in HTML, you also must include ipykernel and nbsphinx.

Add to github repository#

Include created notebooks (.ipynb files) and required files in the repository containing the documentation. It is recommended to include them in a sub directory of the documentation folder, such as (/docs/tutorials). For an example of notebooks used in an existing documentation set, see InstituteforDiseaseModeling/covasim. These notebooks are configured to be run in interactive (dynamic) sessions, if desired. See below for more information on interactive notebooks.

Interactive notebooks#

After following the above steps for creating a static notebook, you can also make the notebook dynamic and interactive. This allows for running the Python examples within the documentation. The additional step needed is to launch the repository containing the Jupyter notebook(s) on mybinder.org. This will then generate a reusable link you can use within the documentation for interactive notebooks.

Note

The repository containing the notebook files must be public in order to use the steps below. If you have a private repository and are unable to make it public then you may create a separate public repository containing the notebook files. For example, see InstituteforDiseaseModeling/jupyter-notebooks-emodpy

Go to mybinder.org
Enter URL for GitHub repository
Select launch

You can then use the reusable link for including interactive notebooks. See best practices section below for additional information.

Best practices#

Include numbers for list ordering of multiple notebooks when using interactive notebooks with BinderHub. For example, if you have a recommended sequential order then you may want to include sequential numbers within the beginning of the title - similar to (tut1_intro, tut2_setup, tut3_analyze).

Note

If you have to reorder and consequently rename the tutorials then you may want to consider using explicit targets when referencing a tutorial instead of using a link reference. For more, see https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#explicit-targets

Design your tutorials as toy examples because of resource limitations using BinderHub (https://mybinder.readthedocs.io/en/latest/about/user-guidelines.html). Keep in mind the time it takes to load and build a notebook. Generally speaking a notebook should take no more than 30 seconds to build.
Include notebooks in a sub directory of the documentation folder, such as (/docs/tutorials).