Today I learned how to write self-documenting Makefiles which allow to write an own CLI tool using make as part of a repository. This is done, by keeping a small selection of make targets around, which get a special annotation that describes the targets purpose and will be exported as “target description” when calling a special help target that filters for this annotation.

help: ## Show this help
	@egrep -h '\s##\s' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'

I came across this wonderful idea while reading the article about “self-documenting Makefiles” by Victoria Drake, that I highly recommend to check out for details on the topic. As a result I sat down and wrote an own set of Makefiles for this blog. There is still some work left, but it’s already an improvement over the original set of shell scripts.