Makefile

# Simple makefile to simplify repetitive build env management tasks under posix

.DEFAULT_GOAL := test

.PHONY: all clean coverage coverage-xml coverage-html coverage-docs docstyle sync-deps lint typecheck test test-core test-plotting doctest docs docs-test-build docs-test-images integration

# `all` is a POSIX convention; alias it to the default test target.
all: test

# Remove build / coverage artifacts from the repo root.
clean:
	@echo "Cleaning build and coverage artifacts"
	@rm -rf build dist .tox .pytest_cache htmlcov coverage*.xml coverage*.html .coverage

# Directories to run style checks against
CODE_DIRS ?= doc examples examples_trame pyvista tests
# Files in top level directory
CODE_FILES ?= *.py *.rst *.md

coverage:
	@echo "Running coverage"
	@pytest -v --cov

coverage-xml:
	@echo "Reporting XML coverage"
	@pytest -v --cov --cov-report xml

coverage-html:
	@echo "Reporting HTML coverage"
	@pytest -v --cov --cov-report html

coverage-docs:
	@echo "Reporting documentation coverage"
	@make -C doc html SPHINXOPTS="-Q" -b coverage
	@cat doc/_build/coverage/python.txt

docstyle:
	@echo "Running vale"
	@python3 doc/run_vale.py

sync-deps:
	@echo "Installing dev dependencies"
	@uv sync --group dev

lint:
	@echo "Running pre-commit"
	@uv run pre-commit run --all-files

# Extra tox args can be passed via ARGS, e.g. `make typecheck ARGS="--notest"`
typecheck:
	@echo "Running mypy"
	@uv run tox -e mypy $(ARGS)

# Forward ARGS as pytest arguments only when set. A bare `--` with nothing after
# it replaces a tox environment's default arguments instead of adding to them
# (see the `{posargs:...}` defaults in tox.ini), which would widen or narrow the
# run in ways the caller did not ask for.
TOX_ARGS = $(if $(strip $(ARGS)),-- $(ARGS))

# Run tests via tox so local runs match CI exactly. Filter/flag definitions
# live in tox.ini so they are maintained in one place.
# Extra pytest args can be passed via ARGS, e.g. `make test ARGS="-n 10 -k filters"`
test:
	@echo "Running full test suite (matches CI flags)"
	@uv run tox -e test $(TOX_ARGS)

# Core tests only (matches CI `pyX.Y-core` env).
test-core:
	@echo "Running core tests (matches CI)"
	@uv run tox -e test-core $(TOX_ARGS)

# Plotting tests only (matches CI `pyX.Y-plotting` env).
test-plotting:
	@echo "Running plotting tests (matches CI)"
	@uv run tox -e test-plotting $(TOX_ARGS)

# Run all docstring checks (matches CI).
# Executes both the doctest-modules and doctest-names tox envs.
doctest:
	@echo "Running docstring tests (matches CI)"
	@uv run tox -f doctest $(TOX_ARGS)

# Build the full documentation (matches CI `tox -e docs-build`).
# Runs pre-gen steps (make_tables, make_external_gallery) and sphinx.
docs:
	@echo "Building documentation (matches CI)"
	@uv run tox -e docs-build $(TOX_ARGS)

# Test the built documentation (matches CI `tox -e docs-test-build`).
# Requires `make docs` to have been run first.
docs-test-build:
	@echo "Testing built documentation (matches CI)"
	@uv run tox -e docs-test-build $(TOX_ARGS)

# Compare documentation-embedded images against cached baselines (matches CI
# `tox -e docs-test-images`). Requires `make docs` to have been run first.
docs-test-images:
	@echo "Comparing documentation images against cached baselines (matches CI)"
	@uv run tox -e docs-test-images $(TOX_ARGS)

# Run an integration test env (matches CI `tox -e integration-<project>`).
# Specify project via PROJECT, e.g. `make integration PROJECT=trame`.
# Supported projects: trame, geovista, mne, pyvistaqt, playwright
integration:
	@test -n "$(PROJECT)" || { echo "Error: PROJECT is required (trame|geovista|mne|pyvistaqt|playwright)"; exit 1; }
	@echo "Running integration-$(PROJECT) tests (matches CI)"
	@uv run tox -e integration-$(PROJECT) $(TOX_ARGS)