Print Makefile help via Python; reorganize targets

Author: stefanv

Makefile

@@ -1,4 +1,5 @@
-# type `make help` to see all options 
+# type `make help` to see all options
+.DEFAULT_GOAL := help
 
 BASEURL ?= 
 
@@ -8,16 +9,21 @@ endif
 
 .PHONY: help prepare teams-clean teams serve clean
 
-# Add help text after each target name starting with '\#\#'
-help:   ## show this help
-	@echo "\nHelp for this makefile"
-	@echo "Possible commands are:"
-	@grep -h "##" $(MAKEFILE_LIST) | grep -v grep | sed -e 's/\(.*\):.*##\(.*\)/    \1: \2/'
-
 prepare:
 	git submodule update --init --recursive
 	python gen_config.py
 
+serve: ## serve the website at http://localhost:1313/
+serve: prepare
+	hugo $(BASEURLARG) --i18n-warnings server -D
+
+html: ## build the static website in ./public
+html: prepare
+	hugo $(BASEURLARG)
+
+clean: ## remove build artifacts
+	rm -rf public
+
 TEAMS_DIR = static/gallery
 TEAMS = emeritus-maintainers maintainers triage-team survey-team web-team
 TEAMS_QUERY = python themes/scientific-python-hugo-theme/tools/team_query.py
@@ -33,14 +39,10 @@ teams-clean: prepare
 	  rm -f $(TEAMS_DIR)/$${team}.html ;\
 	done
 
-teams: | teams-clean $(patsubst %,$(TEAMS_DIR)/%.md,$(TEAMS)) ## generates numpy.org team gallery pages
-
-serve: prepare ## serve the website
-	hugo $(BASEURLARG) --i18n-warnings server -D
-
-html: prepare ## build the website in ./public
-	hugo $(BASEURLARG)
-
-clean: ## remove the build artifacts, mainly the "public" directory
-	rm -rf public
+teams: ## generate numpy.org team gallery pages
+teams: | teams-clean $(patsubst %,$(TEAMS_DIR)/%.md,$(TEAMS))
 
+help:   ## display this message
+	@echo numpy.org make targets
+	@echo ----------------------
+	@python scripts/makefile_to_help.py Makefile

scripts/makefile_to_help.py

@@ -0,0 +1,31 @@
+"""
+Modified from https://github.com/cesium-ml/baselayer
+
+Convert ## style comments after a Makefile target into help text.
+
+Usage: makefile_to_help.py <MAKEFILE>
+
+"""
+
+import sys
+import re
+
+
+if not sys.argv:
+    print("Usage: makefile_to_help.py <MAKEFILE>")
+    sys.exit(0)
+
+
+def describe_targets(lines):
+    matches = [re.match('^([\w-]+): +##(.*)', line) for line in lines]
+    groups = [m.groups(0) for m in matches if m]
+    targets = {target: desc for (target, desc) in groups}
+
+    N = max(len(target) for (target, desc) in targets.items())
+
+    for (target, desc) in targets.items():
+        print(f'{target:{N}} {desc}')
+
+
+fname = sys.argv[1]
+describe_targets(open(fname).readlines())