Develop#

Requires#

git
Make. See Makefile for a list of make commands.

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).

Environment#

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

Install#

After activating the virtual environment, clone the pycontrails repository:

$ cd <install-path>
$ git clone git@github.com:contrailcirrus/pycontrails.git
$ 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

Test#

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#

Documentation is written in reStructuredText and built with Sphinx.

Sphinx configuration is written in docs/conf.py. 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 http://127.0.0.1:8000
$ 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

References#

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

Test#

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