Develop#
Requires#
Developing documentation requires:
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