Document Makefile

Makefile

@@ -1,34 +1,62 @@
-all: test
+doc = sed -n "/^$1/ { x ; p ; } ; s/\#\#/[⚙]/ ; s/\./.../ ; x" ${MAKEFILE_LIST}
 
-uninstall:
-	pip freeze | grep -v "^-e" | xargs pip uninstall -y
+## Same as `make test.
+all: test
 
+## Install project dependencies.
 install:
-	pip install --upgrade pip twine wheel
-	pip install --editable .[dev] --upgrade --use-deprecated=legacy-resolver
-
-clean:
-	rm -rf build dist
-	find . -name '*.pyc' -exec rm \{\} \;
-
-check-syntax-errors:
-	python -m compileall -q .
-
-check-types:
-	mypy openfisca_core && mypy openfisca_web_api
-
-check-style:
-	@# Do not analyse .gitignored files.
-	@# `make` needs `$$` to output `$`. Ref: http://stackoverflow.com/questions/2382764.
-	flake8 `git ls-files | grep "\.py$$"`
-
-format-style:
-	@# Do not analyse .gitignored files.
-	@# `make` needs `$$` to output `$`. Ref: http://stackoverflow.com/questions/2382764.
-	autopep8 `git ls-files | grep "\.py$$"`
-
+	@$(call doc,$@:)
+	@pip install --upgrade pip twine wheel
+	@pip install --editable .[dev] --upgrade --use-deprecated=legacy-resolver
+
+## Install openfisca-core for deployment and publishing.
+build: setup.py
+	@## This allows us to be sure tests are run against the packaged version
+	@## of openfisca-core, the same we put in the hands of users and reusers.
+	@$(call doc,$@:)
+	@python $? bdist_wheel
+	@find dist -name "*.whl" -exec pip install --force-reinstall {}[dev] \;
+
+## Uninstall project dependencies.
+uninstall:
+	@$(call doc,$@:)
+	@pip freeze | grep -v "^-e" | sed "s/@.*//" | xargs pip uninstall -y
+
+## Delete builds and compiled python files.
+clean: \
+	$(shell ls -d * | grep "build\|dist") \
+	$(shell find . -name "*.pyc")
+	@$(call doc,$@:)
+	@rm -rf $?
+
+## Compile python files to check for syntax errors.
+check-syntax-errors: .
+	@$(call doc,$@:)
+	@python -m compileall -q $?
+
+## Run linters to check for syntax and style errors.
+check-style: $(shell git ls-files "*.py")
+	@$(call doc,$@:)
+	@flake8 $?
+
+## Run code formatters to correct style errors.
+format-style: $(shell git ls-files "*.py")
+	@$(call doc,$@:)
+	@autopep8 $?
+
+## Run static type checkers for type errors.
+check-types: openfisca_core openfisca_web_api
+	@$(call doc,$@:)
+	@mypy $?
+
+## Run openfisca-core tests.
 test: clean check-syntax-errors check-style check-types
-	env PYTEST_ADDOPTS="$$PYTEST_ADDOPTS --cov=openfisca_core" pytest
+	@$(call doc,$@:)
+	@env PYTEST_ADDOPTS="${PYTEST_ADDOPTS} --cov=openfisca_core" pytest
 
+## Serve the openfisca Web API.
 api:
-	openfisca serve --country-package openfisca_country_template --extensions openfisca_extension_template
+	@$(call doc,$@:)
+	@openfisca serve \
+		--country-package openfisca_country_template \
+		--extensions openfisca_extension_template