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.
Create Jupyter notebook (https://jupyterlab.readthedocs.io/en/stable/getting_started/overview.html)
nbsphinxin 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 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.
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
Create notebook(s), see https://jupyterlab.readthedocs.io/en/latest/user/notebook.html
You can use VS Code instead of JupyterLab, see https://code.visualstudio.com/docs/datascience/jupyter-notebooks
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
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 https://github.com/InstituteforDiseaseModeling/covasim. These notebooks are configured to be run in interactive (dynamic) sessions, if desired. See below for more information on 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.
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 https://github.com/InstituteforDiseaseModeling/jupyter-notebooks-emodpy
Go to mybinder.org
Enter URL for GitHub repository
You can then use the reusable link for including interactive notebooks. See best practices section below for additional information.
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).
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).