Self documented Makefile - Simple example

Following example shows simple self documented Makefile

• Each target is display with description in single line

• Character : is used to separate target name and description

Hint

• One can use multiple : to separate details in description (different fields)

• Following example uses command column to display tasks in nice format

Important

• If one uses multiple : characters, one should update each description to have the same numbers of :.

Code

# ============================================================================
# Based on page:
#   https://gist.github.com/prwhite/8168133
# 
# Example of self-documented makefile
#
# Add the following 'help' target to your Makefile
# And add help text after each target name starting with '\#\#'
# ============================================================================

.PHONY: help
help: ## Help: Show this help message
	@echo 'usage: make [target] ...'
	@echo
	@echo 'Targets:'
	@echo '========'
	@egrep '^(.+)\:\ ##\ (.+)' ${MAKEFILE_LIST} | column -t -c 2 -s ':#'


.PHONY: bump-ver-patch
bump-ver-patch: ## Helper: Bump version - patch level
	bumpversion patch


.PHONY: validate
validate: ## Validate: Run ansible-lint validator
	@echo ""
	@echo "== Run ansible-lint =="
	ansible-lint tower-*.yml


.PHONY: validate-all
validate-all: ## Validate: Run all validation scripts
validate-all: galaxy_install validate galaxy_remove


.PHONY: galaxy-install
galaxy-install: ## Ansible-galaxy: Install roles
	ansible-galaxy install -r roles/requirements.yml
	@echo ""
	@echo "== Installed roles =="
	ansible-galaxy list


.PHONY: galaxy-remove
galaxy-remove: ## Ansible-galaxy: Remove roles
	@echo "== Removing galaxy roles =="
	ansible-galaxy install -r roles/requirements.yml | \
	        awk '{print $$2}' | xargs -I {} ansible-galaxy remove {}
	@echo ""
	@echo "== Result in 'roles' folder =="
	ls -la roles/


.PHONY: clean
clean: ## Clean: Clean all temporary files
	$(MAKE) -C docs clean
	rm -fr *~

Result

Running make without any arguments will display list of available tasks.

usage: make [target] ...

Targets:
========
help                  Help             Show this help message
bump-ver-patch        Helper           Bump version - patch level
validate              Validate         Run ansible-lint validator
validate-all          Validate         Run all validation scripts
galaxy-install        Ansible-galaxy   Install roles
galaxy-remove         Ansible-galaxy   Remove roles
clean                 Clean            Clean all temporary files

Im result above one can see three columns:

• First is with name of target

• Second is with group for target

• Last is longer description