# Contributing

## Setup

```sh
uv sync --all-extras --dev
git config core.hooksPath .githooks
```

The second command activates the shared pre-commit hook, which runs format, lint, and type-check before every commit.

## Running tests

Tests run using `bpy` installed from pip (no need for Blender on `PATH`)

```sh
uv run pytest -n 4
```

## Regenerating node classes

Most node classes under `src/nodebpy/nodes/` are auto-generated from Blender's live node registry by the `gen/` package (kept outside `src/` so it never ships in the wheel). After a Blender / `bpy` version change, regenerate with:

```sh
make generate
```

which runs, in order:

1. `uv run python -m nodebpy.assets` — regenerates the typed classes for Blender's bundled essentials asset libraries
2. `uv run python -m gen` — regenerates the node classes for every tree type
3. `make format` — `ruff format`, `ruff check --fix`, and `ty check --fix src`

For faster iteration you can regenerate a single tree type:

```sh
uv run python -m gen --only geometry
```

(Geometry is always processed first because the shader and compositor trees re-export shared nodes from it.)

Inside `gen/`: `config.py` holds the per-tree-type configuration and the skip / hand-written / generate disposition for each node, `customizations.py` is the `register_customization` registry that layers generation-time mixins onto specific nodes, `introspect.py` inspects the live node registry, and `model.py` / `emit.py` / `writers.py` turn the results into module files.

Nodes that need special handling are hand-written in `src/nodebpy/nodes/*/manual.py` (and the zone nodes in `nodes/geometry/zone.py` / `nodes/shader/zone.py`); the generator skips these and re-exports them alongside the generated classes.

## Building the docs

The documentation is a [Quarto](https://quarto.org) site under `docs/`, with the API reference generated by `quartodoc`:

```sh
make docs
```

## CI

Two GitHub Actions workflows run on every push and pull request:

- **lint.yml** — ruff format check, ruff check, ty check (Ubuntu only, platform-independent)
- **tests.yml** — pytest on macOS, Windows, and Ubuntu
