Comment the makefile

Makefile

+# Root of the tree of source files.
+# The build converts *.md only, any copies all other files verbatim.
 SRC := content
+
+# Publishable tree, generated from $(SRC).
+# Have a look, but don't edit those.
 OUT := output
 
+# Sets of source files or build targets. Internal.
 SRC_MARKUP := $(shell find $(SRC) -type f -name '*.md')
 SRC_OTHERS := $(shell find $(SRC) -type f -not -name '*.md')
 SRC_DIRS   := $(shell find $(SRC) -type d -mindepth 1)
@@ -9,14 +15,14 @@ OUT_MARKUP := $(SRC_MARKUP:$(SRC)/%.md=$(OUT)/%.php)
 OUT_OTHERS := $(SRC_OTHERS:$(SRC)/%=$(OUT)/%)
 OUT_DIRS   := $(SRC_DIRS:$(SRC)/%=$(OUT)/%)
 
-.PHONY: prepare build publish clean
+.PHONY: build publish clean
 .DEFAULT_GOAL := build
 
-prepare : $(OUT)/.git
+# Main entry point targets
 
-build : $(OUT_MARKUP) $(OUT_OTHERS)
+build : $(OUT_MARKUP) $(OUT_OTHERS) ## Generate publishable files, converting *.md to *.php
 
-publish : | prepare build
+publish : | $(OUT)/.git build ## Build then push to the 'public' branch if there are changes
 	if [ -n "$$(git -C $(OUT) status --porcelain)" ]; then \
 		cd $(OUT) ;\
 		git add . ;\
@@ -24,12 +30,16 @@ publish : | prepare build
 		git push --push-option ci.skip origin 'HEAD:public' ;\
 	fi
 
-clean :
+clean : ## Wipe all generated files
 	rm -fr $(OUT)
 	git worktree prune
 
+# Ensure $(OUT) is setup for publishing, by making it a wortree for the 'public' branch.
+# Under CI, commit as whoever caused the build, but authentify using a token (environment variable
+# DEPLOY_TOKEN set from the gitlab side)
 $(OUT)/.git :
-	git fetch origin public
+	make clean
+	git fetch origin 'public:public'
 	git worktree add --no-checkout $(OUT) public
 	if [ "$$CI" == 'true' -a -n "$$DEPLOY_TOKEN" ]; then \
 		git config user.name  "$$GITLAB_USER_NAME" ;\
@@ -43,10 +53,26 @@ $(OUT) :
 $(OUT_DIRS) : $(OUT)
 	@mkdir -p $@
 
-.SECONDEXPANSION: # oooh, magic *_*
+.SECONDEXPANSION: # oooh, magic *_* (needed to ensure parent directories exist)
 
 $(OUT)/% : $(SRC)/% | $$(@D)
 	cp $< $@
 
 $(OUT)/%.php : $(SRC)/%.md signature.html | $$(@D)
 	pandoc --output $@ --template signature --from markdown --to html $<
+
+# Some shell magic to auto-document the main targets. To have a target appear in
+# the output, add a short, one-line comment with a double ## on the same line as
+# the target.
+#
+# See http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
+
+.PHONY: help
+
+help: ## Describe the main targets (this list)
+	@echo "Main targets you can build:"
+	@awk -F ':|## *' \
+		'/^[^\t].+:[^=].*##/ {\
+			printf "  \033[36m%s\033[0m#%s\n", $$1, $$NF \
+		}' $(MAKEFILE_LIST) \
+	| column -s# -t