Developer Guide

This guide covers setting up a development environment, running tests, and building the documentation. For a broader introduction to best practices for scientific Python packages, see the Scientific Python Developer Guide.

Quick development

The recommended way to develop kwneuro is with uv. Install uv following the official instructions, then clone the repo and sync:

git clone https://github.com/brain-microstructure-exploration-tools/kwneuro.git
cd kwneuro
uv sync --extra dev

This creates a virtual environment under .venv/, installs kwneuro in editable mode with all development dependencies (including all optional extras), and respects the committed uv.lock for reproducible installs.

Note

CI uses uv sync --extra test, which installs only the lightweight optional deps needed for tests (neuroCombat). The heavier optional deps (HD-BET, TractSeg, AMICO) are mocked in tests and not required in CI.

Common tasks:

uv run pytest                            # Run tests
uv run pytest --cov=kwneuro              # Run tests with coverage
uv run pre-commit run --all-files        # Format + fast lint
uv run pylint kwneuro                    # Thorough lint (slow)

Setting up without uv

You can also set up a development environment with plain pip:

python3 -m venv .venv
source ./.venv/bin/activate
pip install -e ".[dev]"

Pre-commit

This project uses pre-commit for all style checking. Install the hook so it runs automatically on each commit:

uv run pre-commit install

You can also run it manually:

uv run pre-commit run --all-files

Testing

uv run pytest

Coverage

uv run pytest --cov=kwneuro

Building docs

uv run --extra docs sphinx-build -n -T docs docs/_build/html

To live-preview while editing:

uv run --extra docs sphinx-autobuild -n -T docs docs/_build/html

Rebuilding tutorial pages from notebooks

The tutorial pages under docs/tutorials/ are pre-rendered Markdown files generated from the Jupytext notebooks in notebooks/. To regenerate them (e.g., after editing a notebook), use the conversion script:

# Rebuild all tutorials (needs all optional extras installed)
uv run --extra notebooks --extra all python scripts/update-notebook-pages.py

# Rebuild just one tutorial
uv run --extra notebooks --extra combat python scripts/update-notebook-pages.py \
    notebooks/example-harmonization.py

The script executes each notebook and exports the results as Markdown with images. The output files in docs/tutorials/ should be committed to git so that the docs build on ReadTheDocs does not need to execute notebooks.

Running the example notebooks

The notebooks/ directory contains Jupytext percent-format .py files. Each notebook may require different optional extras. See notebooks/README.md for per-notebook instructions, or install everything at once:

uv sync --extra notebooks --extra all
cd notebooks
uv run jupytext --to ipynb example-harmonization.py
uv run jupyter notebook example-harmonization.ipynb