A Makefile help target
The longer I’m around in this industry, the more I rely on Makefiles to remember all the steps I need to take. If something else doesn’t put the steps in order, I’m not likely to remember everything myself. This website even has a /Makefile (it is all in a public GitHub repo, so have at it), and it has a feature that I’ve come to love.
François Zaninotto wrote about Self-documented Makefile. He didn’t really document the Makefile so much as give it a target summary like you’d get from rake:
$ make help
error show the error from the last build
help show a list of targets
publish Remake stuff and send it to GitHub
rebuild tell GitHub to rebuild the site
setup setup the tools (try to install what you need)
show_vars show some variables, useful for debugging
spell spellcheck the markdown files in _posts/
status show the GitHub Pages build status
tag create the tag filesUsually I know I have a target for something but I forget the name. Although I usually have the Makefile open, I have an easier time with make help. That is, when I remember to use it.
It’s an easy task. Grep the Makefile for targets (which is very easy because the targets start at the first column) and check if there’s a ## comment after it. Sort what you find and format it.
######################################################################
# https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
.PHONY: help ## Show all the Makefile targets with descriptions
help: ## show a list of targets
@grep -E '^[a-zA-Z][/a-zA-Z0-9_.-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'