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.