From a18123762e95f775aa02648392642a5f597f85ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rapha=C3=ABl=20Barrois?= <raphael.barrois@polytechnique.org>
Date: Wed, 28 Aug 2019 20:03:03 +0200
Subject: Add `make help`.

---
 Makefile | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 53 insertions(+), 5 deletions(-)

diff --git a/Makefile b/Makefile
index c0f0523..6f77a93 100644
--- a/Makefile
+++ b/Makefile
@@ -11,6 +11,12 @@ all: default
 
 default:
 
+.PHONY: all default
+
+
+# Package management
+# ==================
+
 
 clean:
 	find . -type f -name '*.pyc' -delete
@@ -24,34 +30,76 @@ update:
 	pip install --upgrade -r requirements_dev.txt
 	pip freeze
 
+
+.PHONY: clean update
+
+# Tests and quality
+# =================
+
+
+# DOC: Run tests for all supported versions (creates a set of virtualenvs)
 testall:
 	tox
 
 
+# DOC: Run tests for the currently installed version
 test:
-	python -W default setup.py test
+	python -Wdefault setup.py test
 
-# Note: we run the linter in two runs, because our __init__.py files has specific warnings we want to exclude
+# DOC: Perform code quality tasks
 lint: check-manifest flake8
 
+# DOC: Verify that MANIFEST.in and .gitignore are consistent
 check-manifest:
 	check-manifest
 
+# Note: we run the linter in two runs, because our __init__.py files has specific warnings we want to exclude
+# DOC: Verify code quality
 flake8:
 	$(FLAKE8) --config .flake8 --exclude $(PACKAGE)/__init__.py $(PACKAGE) $(TESTS_DIR) setup.py
 	$(FLAKE8) --config .flake8 --ignore F401 $(PACKAGE)/__init__.py
 
+# DOC: Run tests with coverage collection
 coverage:
 	$(COVERAGE) erase
 	$(COVERAGE) run "--include=$(PACKAGE)/*.py,$(TESTS_DIR)/*.py" --branch setup.py test
 	$(COVERAGE) report "--include=$(PACKAGE)/*.py,$(TESTS_DIR)/*.py"
 	$(COVERAGE) html "--include=$(PACKAGE)/*.py,$(TESTS_DIR)/*.py"
 
-coverage-xml-report: coverage
-	$(COVERAGE) xml "--include=$(PACKAGE)/*.py,$(TESTS_DIR)/*.py"
+.PHONY: testall test lint check-manifest flake8 coverage
+
+
+# Documentation
+# =============
+
 
+# DOC: Compile the documentation
 doc:
 	$(MAKE) -C $(DOC_DIR) html
 
 
-.PHONY: all default clean coverage doc install-deps lint test
+# DOC: Show this help message
+help:
+	@grep -A1 '^# DOC:' Makefile \
+	 | awk '    					\
+	    BEGIN { FS="\n"; RS="--\n"; opt_len=0; }    \
+	    {    					\
+		doc=$$1; name=$$2;    			\
+		sub("# DOC: ", "", doc);    		\
+		sub(":", "", name);    			\
+		if (length(name) > opt_len) {    	\
+		    opt_len = length(name)    		\
+		}    					\
+		opts[NR] = name;    			\
+		docs[name] = doc;    			\
+	    }    					\
+	    END {    					\
+		pat="%-" (opt_len + 4) "s %s\n";    	\
+		asort(opts);    			\
+		for (i in opts) {    			\
+		    opt=opts[i];    			\
+		    printf pat, opt, docs[opt]    	\
+		}    					\
+	    }'
+
+.PHONY: doc help
-- 
cgit v1.2.1