Add make help recipe (#609)

Makefile

@@ -1,12 +1,34 @@
 .POSIX:
 
+# Recipes for this Makefile
+
+## Build shards
+##   $ make
+## Build shards in release mode
+##   $ make release=1
+## Run tests
+##   $ make test
+## Run tests without fossil tests
+##   $ make test skip_fossil=1
+## Generate docs
+##   $ make docs
+## Install shards
+##   $ make install
+## Uninstall shards
+##   $ make uninstall
+## Build and install shards
+##   $ make build && sudo make install
+
 release ?=      ## Compile in release mode
 debug ?=        ## Add symbolic debug info
 static ?=       ## Enable static linking
 skip_fossil ?=  ## Skip fossil tests
 skip_git ?=     ## Skip git tests
 skip_hg ?=      ## Skip hg tests
 
+DESTDIR ?=          ## Install destination dir
+PREFIX ?= /usr/local## Install path prefix
+
 CRYSTAL ?= crystal
 SHARDS ?= shards
 override FLAGS += $(if $(release),--release )$(if $(debug),-d )$(if $(static),--static )
@@ -20,8 +42,6 @@ SHARDS_CONFIG_BUILD_COMMIT := $(shell git rev-parse --short HEAD 2> /dev/null)
 SHARDS_VERSION := $(shell cat VERSION)
 SOURCE_DATE_EPOCH := $(shell (git show -s --format=%ct HEAD || stat -c "%Y" Makefile || stat -f "%m" Makefile) 2> /dev/null)
 EXPORTS := SHARDS_CONFIG_BUILD_COMMIT="$(SHARDS_CONFIG_BUILD_COMMIT)" SOURCE_DATE_EPOCH="$(SOURCE_DATE_EPOCH)"
-DESTDIR ?=
-PREFIX ?= /usr/local
 BINDIR ?= $(DESTDIR)$(PREFIX)/bin
 MANDIR ?= $(DESTDIR)$(PREFIX)/share/man
 INSTALL ?= /usr/bin/install
@@ -33,31 +53,38 @@ all: build
 
 include docs.mk
 
+build: ## Build shards
 build: phony bin/shards
 
+clean: ## Remove build artifacts
 clean: phony clean_docs
 	rm -f bin/shards
 
 bin/shards: $(SOURCES) $(TEMPLATES) lib
 	@mkdir -p bin
 	$(EXPORTS) $(CRYSTAL) build $(FLAGS) src/shards.cr -o bin/shards
 
+install: ## Install shards
 install: bin/shards man/shards.1.gz man/shard.yml.5.gz phony
 	$(INSTALL) -m 0755 -d "$(BINDIR)" "$(MANDIR)/man1" "$(MANDIR)/man5"
 	$(INSTALL) -m 0755 bin/shards "$(BINDIR)"
 	$(INSTALL) -m 0644 man/shards.1.gz "$(MANDIR)/man1"
 	$(INSTALL) -m 0644 man/shard.yml.5.gz "$(MANDIR)/man5"
 
+uninstall: ## Uninstall shards
 uninstall: phony
 	rm -f "$(BINDIR)/shards"
 	rm -f "$(MANDIR)/man1/shards.1.gz"
 	rm -f "$(MANDIR)/man5/shard.yml.5.gz"
 
+test: ## Run all tests
 test: test_unit test_integration
 
+test_unit: ## Run unit tests
 test_unit: phony lib
 	$(CRYSTAL) spec ./spec/unit/ $(if $(skip_fossil),--tag ~fossil) $(if $(skip_git),--tag ~git) $(if $(skip_hg),--tag ~hg)
 
+test_integration: ## Run integration tests
 test_integration: bin/shards phony
 	$(CRYSTAL) spec ./spec/integration/
 
@@ -72,3 +99,20 @@ man/%.gz: man/%
 	gzip -c -9 $< > $@
 
 phony:
+
+.PHONY: help
+help: ## Show this help
+	@echo
+	@printf '\033[34mtargets:\033[0m\n'
+	@grep -hE '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) |\
+		sort |\
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
+	@echo
+	@printf '\033[34moptional variables:\033[0m\n'
+	@grep -hE '^[a-zA-Z_-]+ \?=.*?## .*$$' $(MAKEFILE_LIST) |\
+		sort |\
+		awk 'BEGIN {FS = " \\?=.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
+	@echo
+	@printf '\033[34mrecipes:\033[0m\n'
+	@grep -hE '^##.*$$' $(MAKEFILE_LIST) |\
+		awk 'BEGIN {FS = "## "}; /^## [a-zA-Z_-]/ {printf "  \033[36m%s\033[0m\n", $$2}; /^##  / {printf "  %s\n", $$2}'

docs.mk

@@ -8,10 +8,13 @@ HTML_FILES := docs/shards.html docs/shard.yml.html
 SHARDS_VERSION := $(shell cat VERSION)
 SOURCE_DATE_EPOCH := $(shell (git show -s --format=%ct HEAD || stat -c "%Y" Makefile || stat -f "%m" Makefile) 2> /dev/null)
 
+docs: ## Build documentation
 docs: manpages
 
+manpages: ## Generate manpages from adoc
 manpages: $(MAN_FILES)
 
+htmlpages: ## Generate HTML files from adoc
 htmlpages: $(HTML_FILES)
 
 man/%.1 man/%.5: docs/%.adoc
@@ -20,6 +23,7 @@ man/%.1 man/%.5: docs/%.adoc
 docs/%.html: docs/%.adoc
 	SOURCE_DATE_EPOCH=$(SOURCE_DATE_EPOCH) $(ASCIIDOC) $(ASCIIDOC_OPTIONS) $< -b html5 -o $@
 
+clean_docs: ## Remove documentation data
 clean_docs: phony
 	rm -f $(MAN_FILES)
 	rm -rf docs/*.html