pre-commit hook

.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+default_language_version:
+  python: python3.10
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v3.2.0
+  hooks:
+  - id: trailing-whitespace
+  - id: end-of-file-fixer
+  - id: check-toml
+  - id: check-yaml
+  - id: check-added-large-files
+
+- repo: local
+  hooks:
+
+  - id: black
+    name: black
+    entry: black
+    language: system
+    types: [python]
+    args: [--check]
+
+  - id: isort
+    name: isort
+    entry: isort
+    language: system
+    types: [python]
+    args: [--check,--profile=black]
+
+  - id: ruff
+    name: ruff
+    entry: ruff
+    language: system
+    types: [python]
+
+  - id: mypy
+    name: mypy
+    entry: mypy
+    language: system
+    types: [python]

CONTRIBUTING.md

@@ -1,34 +1,114 @@
-# Contributing to Kalamine
+Contributing to Kalamine
+================================================================================
 
-In order to contribute to Kalamine, you need to install the development dependencies. 
-After checking out the repository, you can install both the current version of kalamine and those dependencies using `pip install .[dev]`.
-Alternatively you can explicitly run `pip install black isort ruff pytest mypy types-PyYAML`.
 
-Then we strongly advise you to setup a git pre-commit hook that check things that will be checked by contnuous integration on GitHub.
-You simply need to create inside the project root folder a executable file `.git/hooks/pre-commit` containing:
+Setup
+--------------------------------------------------------------------------------
+
+After checking out the repository, you can install kalamine and its development dependencies like this:
+
 ```bash
-#!/bin/sh
+python3 -m pip install --user .[dev]
+```
+
+Which is the equivalent of:
+
+```bash
+python3 -m pip install --user -e .
+python3 -m pip install --user build black isort ruff pytest mypy types-PyYAML pre-commit
+```
+
+And if you prefer the old-school way, there’s a Makefile recipe for that:
+
+```bash
+make dev
+```
+
+
+Code Formating
+--------------------------------------------------------------------------------
 
-echo "Running black" &&
-black --check --quiet kalamine &&
-echo "Running isort" &&
-isort --check --quiet kalamine &&
-echo "Running ruff" &&
-ruff kalamine &&
-echo "Running pytest" &&
-pytest --quiet &&
-echo "Running mypy" &&
-mypy kalamine 
+We rely on [black][1] and [isort][2] for that, with their default configurations:
+
+```bash
+black kalamine
+isort kalamine
+```
+
+Old-school alternative:
+
+```bash
+make format
 ```
 
+[1]: https://black.readthedocs.io
+[2]: https://pycqa.github.io/isort/
+
+
+Code Linting
+--------------------------------------------------------------------------------
+
+We rely on [ruff][3] and [mypy][4] for that, with their default configurations:
+
+```bash
+black --check --quiet kalamine
+isort --check --quiet kalamine
+ruff kalamine
+mypy kalamine
+```
+
+Old-school alternative:
+
+```bash
+make lint
+```
+
+Many linting errors can be fixed automatically:
+
+```bash
+ruff --fix kalamine
+```
+
+[3]: https://docs.astral.sh/ruff/
+[4]: https://mypy.readthedocs.io
+
+
+Unit Tests
+--------------------------------------------------------------------------------
+
+We rely on [pytest][5] for that, but the sample layouts must be built by
+kalamine first:
+
+```bash
+python3 -m kalamine.cli make layouts/*.toml
+pytest
+```
+
+Old-school alternative:
+
+```bash
+make test
+```
+
+[5]: https://docs.pytest.org
+
+
+Before Committing
+--------------------------------------------------------------------------------
+
+Then we strongly advise you to setup a git pre-commit hook that check things that will be checked by contnuous integration on GitHub.
+
 This is asking git to run the above commands before any commit is created, and to abort the commit if any of them fail.
-You can find more information about those tools on the web sites of 
-[black](https://black.readthedocs.io/),
-[isort](https://pycqa.github.io/isort/),
-[ruff](https://docs.astral.sh/ruff/), 
-[mypy](https://mypy.readthedocs.io/), 
-[pytest](https://docs.pytest.org/). 
-Note that errors flagged by the first three of them can often be automatically fixed, using
-`black kalamine`, `isort kalamine` and `ruff --fix kalamine` respectively.
 
+The fancy way to do this relies on `pre-commit` and `node.js`:
 
+```bash
+pre-commit install
+```
+
+Old-school alternative, create an executable file `.git/hooks/pre-commit` containing:
+
+```bash
+#!/bin/sh
+make
+```

Makefile

@@ -1,32 +1,33 @@
 .PHONY: all dev test lint publish format clean
 
-all: test
+all: format lint test
 
 dev:  ## Install a development environment
+	python3 -m pip install --user .[dev]
+	# python3 -m pip install --user --upgrade build
 	# python3 -m pip install --user --upgrade twine wheel
-	python3 -m pip install --user --upgrade build
-	python3 -m pip install --user -e .
 
+format:  ## Format sources
+	black kalamine
+	isort kalamine
+
+lint:  ## Lint sources
+	black --check --quiet kalamine
+	isort --check --quiet kalamine
+	ruff kalamine
+	mypy kalamine
 
 test:  ## Run tests
 	python3 -m kalamine.cli guide > docs/README.md
 	python3 -m kalamine.cli make layouts/*.toml
 	pytest
 
 publish: test  ## Publish package
-	# flake8 kalamine
 	rm -rf dist/*
 	python3 -m build
 	twine check dist/*
 	twine upload dist/*
 
-lint:  ## Lint sources
-	flake8 kalamine
-
-format:  ## Format sources
-	isort .
-	black .
-
 clean:  ## Clean sources
 	rm -rf build
 	rm -rf dist

pyproject.toml

@@ -40,7 +40,8 @@ dev = [
     "ruff",
     "pytest",
     "mypy",
-    "types-PyYAML"
+    "types-PyYAML",
+    "pre-commit",
 ]
 
 [project.urls]