Developing documentation requires:
Create a dedicated virtual environment for development:
# create environment in <DIR> $ python3 -m venv <DIR> # activate environment (Unix-like) $ source <DIR>/bin/activate
# 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 firstname.lastname@example.org:contrailcirrus/pycontrails.git $ cd pycontrails
Install the development verison of
$ 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
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 -b html docs docs/_build/html # HTML output
Sphinx caches builds between changes.
To force the whole site to rebuild, use the options
$ sphinx-build -aE -b html docs docs/_build/html # rebuild all output
See sphinx-build for a list of all the possible output builders.
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
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 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.biband press Save to overwrite the file.
Commit the updated
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