See the [Scientific Python Developer Guide][spc-dev-intro] for a detailed
description of best practices for developing scientific packages.

[spc-dev-intro]: https://learn.scientific-python.org/development/

# Setting up a development environment

You can set up a development environment with `conda` or your environment
manager of choice:

```bash
conda create -n iceflow-dev pip "python =3.12"
conda activate iceflow-dev
pip install --editable .[dev]
```

# Pre-commit

You should prepare pre-commit, which will help you by checking that commits pass
required checks:

```bash
pre-commit install # Will install a pre-commit hook into the git repo
```

You can also/alternatively run `pre-commit run` (changes only) or
`pre-commit run --all-files` to check without installing the hook.

# Common tasks

Common dev tasks are handled by [invoke](https://www.pyinvoke.org/). To see
available tasks:

```
$ inv -l
Available tasks:

  test.all (test)              Run all of the tests.
  test.pytest                  Run all tests with pytest.
  test.typecheck (test.mypy)   Run mypy typechecking.
```

# Jupyter Notebooks

There are Jupyter Notebooks showing `iceflow` functionality under `notebooks/`.

To get started with developing existing or new notebooks, first install the
notebook-specific dependencies:

```
pip install --editable .[notebooks]
```

Then:

```
cd notebooks/
jupyter lab
```

Develop notebooks and confirm that they work as expected. Before committing
changes, clear all outputs.

See below for information about adding rendered versions of notebooks to
ReadTheDocs.

# Documentation

This project uses `sphinx` to generate documentation. To work on the docs,
install the dependencies:

```bash
pip install -e .[docs]
```

Use the included `docs.watch` task to actively work on the docs with
live-reloading:

```
inv docs.watch
```

The docs are generated and hosted by
[ReadTheDocs](https://iceflow.readthedocs.io/en/latest/).

When creating a PR, a ReadTheDocs will generate a preview of the documentation.
Please review this carefully and ensure that any changes are accurately
reflected. On a merge to main, changes to the documentation will be reflected on
the main, public-facing documentation site.

> [!NOTE] Most of the documentation is designed to be generated automatically.
> E.g., changes to the API and markdown documents will be automatically
> refelcted in the documentation. The one exception are the jupyter notebooks
> (e.g., `iceflow-example.ipynb`), which are static and must be re-generated
> manually. Use the `invoke docs.render-notebooks-for-docs` task to re-generate
> these files, and then commit any changes to the repository. See the
> `notebooks/generate_rendered_notebooks_for_docs.sh` for how to add new
> rendered notebooks to the docs.

# Releasing

To release a new version of the software, first update the CHANGELOG.md to
reflect the version you plan to release. Then, bump the version with
[bump-by-version](https://github.com/callowayproject/bump-my-version):

```
$ bump-my-version bump {major|minor|patch}
```

This will update files containing the software version number.

> [!WARNING]
>
> Please do not attempt to update version numbers by hand!

Commit these changes and, once ready, merge them into `main` (through the use of
a Pull Request on a feature branch). Tag the commit you want to release on
`main` to initiate a GitHub Action (GHA) that will release the package to
anaconda.org.
