Development

Documentation

To rebuild the documentation, install several packages:

pip install -r docs/requirements.txt

And then run from the docs directory:

make html

This can take a long time because it executes many of the examples; if you’d prefer to build the docs without executing the notebooks, you can run:

make html-noplot

You can then see the generated documentation in docs/_build/html/index.html.

Update notebooks

We use jupytext to maintain two synced copies of the notebooks in docs/notebooks: one in ipynb format, and one in md format. The advantage of the former is that it can be opened and executed directly in Colab; the advantage of the latter is that it makes it much easier to track diffs within version control.

Editing ipynb

For making large changes that substantially modify code and outputs, it is easiest to edit the notebooks in Jupyter or in Colab. To edit notebooks in the Colab interface, open http://colab.research.google.com and Upload from your local repo. Update it as needed, Run all cells then Download ipynb. You may want to test that it executes properly, using sphinx-build as explained above.

Editing md

For making smaller changes to the text content of the notebooks, it is easiest to edit the .md versions using a text editor.

Syncing notebooks

After editing either the ipynb or md versions of the notebooks, you can sync the two versions using jupytext. For example, to sync the files inside the docs/notebooks/deep_learning/, run the command:

jupytext --sync docs/notebooks/deep_learning/*.*

Be sure to use the version of jupytext specified in .pre-commit-config.yaml.

Alternatively, you can use the pre-commit framework to run this on all staged files in your git repository, automatically using the correct jupytext version:

pre-commit run jupytext

See the pre-commit framework documentation for information on how to set your local git environment to execute this automatically.

Creating new notebooks

If you are adding a new notebook to the documentation and would like to use the jupytext --sync command discussed here, you can set up your notebook for jupytext by using the following command:

jupytext --set-formats ipynb,md:myst path/to/the/notebook.ipynb

This works by adding a "jupytext" metadata field to the notebook file which specifies the desired formats, and which the jupytext --sync command recognizes when invoked.

Notebooks within the sphinx build

We exclude some notebooks from the build, e.g., because they contain long computations. See exclude_patterns in conf.py.