Developing documentation requires:

  • pandoc for interpreting Jupyter notebooks

  • LaTeX for pdf outputs. If you are using a Mac, MacTeX is the best option. Note that LaTeX can be fairly large to install (~6GB).


Create a dedicated virtual environment for development:

# create environment in <DIR>
$ python3 -m venv <DIR>

# activate environment (Unix-like)
$ source <DIR>/bin/activate

If using Anaconda / Miniconda Python, create a dedicated Anaconda environment:

# create conda environment
$ conda create -n contrails python=3.10

# activate environment
$ conda activate contrails


After activating the virtual environment, clone the pycontrails repository:

$ cd <install-path>
$ git clone
$ cd pycontrails

Install the development verison of pycontrails using make:

$ make dev-install

or install dependencies manually using pip in editable mode:

# core development installation
$ pip install -e ".[docs,dev]"

# install optional dependencies as above
$ pip install -e ".[ecmwf,gfs]"

# make sure to add pre-commit hooks if installing manually
$ pre-commit install


Run all code quality checks and unit tests. This is run in the test workflow, but should also be run locally before submitting PRs:

$ make test

Lint the repository with ruff:

$ make ruff

Autoformat the repository with black:

$ make black

Run type checking with mypy:

$ make mypy

Run unit tests with pytest:

$ make pytest


Documentation is written in reStructuredText and built with Sphinx.

Sphinx configuration is written in docs/ See Sphinx configuration docs for the full list of configuration options.

Build HTML documentation:

# docs build to directory docs/_build/html
$ make docs-build

# automatically build docs on changes
# docs will be served at
$ make docs-serve

# clean up built documentation
$ make docs-clean

Build manually with sphinx-build:

$ sphinx-build -b html docs docs/_build/html      # HTML output

Sphinx caches builds between changes. To force the whole site to rebuild, use the options -aE:

$ sphinx-build -aE -b html docs docs/_build/html  # rebuild all output

See sphinx-build for a list of all the possible output builders.

PDF Output#

Building PDF output requires a LaTeX distribution.

Build pdf documentation:

$ make docs-pdf

A single pdf output (i.e. pycontrails.pdf) will be built within docs/_build/latex.

To build manually, run:

$ sphinx-build -b latex docs docs/_build/latex
$ cd docs/_build/latex
$ make


Literature references managed in the pycontrails Zotero library.

To automatically sync this library with the docs/_static/pycontrails.bib Bibtex file:

  • Install Zotero and add the pycontrails library.

  • Install the Zotero Better Bibtex extension. Leave defaults during setup.

  • Right click on the pycontrails library and select Export Library

  • Export as Better Bibtex. You can optionally check Keep Updated if you want this file to update every time you make a change to the library.

  • Select the file _static/pycontrails.bib and press Save to overwrite the file.

  • Commit the updated _static/pycontrails.bib


All doc tests first ensure ERA5 data is cached locally:

$ make ensure-era5-cached

Run rst linter with doc8:

$ make pytest

Run docstring example tests with doctest:

$ make doctest

Test notebook examples with nbval pytest plugin:

$ make nbtest