installation.qmd

# Installation

PlotNado uses standard Python packaging, but the recommended workflow is `uv`.

## Requirements

- Python 3.12+
- `uv`
- Quarto, only if you are building the public documentation site

## Install `uv`

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

On macOS:

```bash
brew install uv
```

## Use PlotNado as a CLI

For a user-level command:

```bash
uv tool install plotnado
plotnado --help
```

From a checked-out repository, prefer:

```bash
uv run plotnado --help
```

## Develop from source

```bash
git clone https://github.com/alsmith151/plotnado
cd plotnado
uv sync --extra dev --extra docs
uv run pytest tests/
uv run python examples/run_examples.py
uv run plotnado --help
```

`uv sync --extra dev --extra docs` installs the package, test tools, and documentation dependencies into the project environment.

## Build docs locally

```bash
uv sync --extra dev --extra docs
QUARTO_PYTHON=.venv/bin/python quarto render
QUARTO_PYTHON=.venv/bin/python quarto preview
```

The docs use executable Quarto Python cells. Most examples use deterministic in-memory data; optional cooler, CapCruncher, and QuantNado examples need their corresponding dependencies and fixture data.

## Pip and Conda

`pip` and Conda environments can still install PlotNado, but project development and docs examples assume the `uv` commands above.

```bash
python -m venv .venv
source .venv/bin/activate
pip install plotnado
```