From 792c1088130c7e7f9b49c81b7f390fe10d5f776c Mon Sep 17 00:00:00 2001
From: Jiri Podivin <jpodivin@redhat.com>
Date: Mon, 6 May 2024 11:04:23 +0200
Subject: [PATCH] Adding help for Makefile

Signed-off-by: Jiri Podivin <jpodivin@redhat.com>
---
 Makefile | 33 +++++++++++++++++++++++++--------
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/Makefile b/Makefile
index 01a86cf40..015275e70 100644
--- a/Makefile
+++ b/Makefile
@@ -4,15 +4,32 @@ TEST_SECRETS ?= tests/secrets.yaml
 TEST_CONFIG ?= tests/ansible.cfg
 TEST_ARGS ?=
 
-### TESTS ###
+##@ General
+
+# The help target prints out all targets with their descriptions organized
+# beneath their categories. The categories are represented by '##@' and the
+# target descriptions by '##'. The awk commands is responsible for reading the
+# entire set of makefiles included in this invocation, looking for lines of the
+# file as xyz: ## something, and then pretty-format the target and help. Then,
+# if there's a line with ##@ something, that gets pretty-printed as a category.
+# More info on the usage of ANSI control characters for terminal formatting:
+# https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
+# More info on the awk command:
+# http://linuxcommand.org/lc3_adv_awk.php
+
+.PHONY: help
+help: ## Display this help.
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+
+##@ TESTS 
 
 test-minimal: TEST_OUTFILE := tests/logs/test_minimal_out_$(shell date +%FT%T%Z).log
-test-minimal:
+test-minimal:  ## Launch minimal test suite
 	mkdir -p tests/logs
 	ANSIBLE_CONFIG=$(TEST_CONFIG) ansible-playbook -v -i $(TEST_INVENTORY) -e @$(TEST_VARS) -e @$(TEST_SECRETS) $(TEST_ARGS) tests/playbooks/test_minimal.yaml 2>&1 | tee $(TEST_OUTFILE)
 
 test-with-ceph: TEST_OUTFILE := tests/logs/test_with_ceph_out_$(shell date +%FT%T%Z).log
-test-with-ceph:
+test-with-ceph:  ## Launch test suite with ceph
 	mkdir -p tests/logs
 	ANSIBLE_CONFIG=$(TEST_CONFIG) ansible-playbook -v -i $(TEST_INVENTORY) -e @$(TEST_VARS) -e @$(TEST_SECRETS) $(TEST_ARGS) tests/playbooks/test_with_ceph.yaml 2>&1 | tee $(TEST_OUTFILE)
 
@@ -32,15 +49,15 @@ test-rollback-with-ceph:
 	ANSIBLE_CONFIG=$(TEST_CONFIG) ansible-playbook -v -i $(TEST_INVENTORY) -e @$(TEST_VARS) -e @$(TEST_SECRETS) $(TEST_ARGS) tests/playbooks/test_rollback_with_ceph.yaml 2>&1 | tee $(TEST_OUTFILE)
 
 test-with-ironic: TEST_OUTFILE := tests/logs/test_with_ironic_out_$(shell date +%FT%T%Z).log
-test-with-ironic:
+test-with-ironic: ## Launch test suite with Ironic
 	mkdir -p tests/logs
 	ANSIBLE_CONFIG=$(TEST_CONFIG) ansible-playbook -v -i $(TEST_INVENTORY) -e @$(TEST_VARS) -e @$(TEST_SECRETS) tests/playbooks/test_with_ironic.yaml 2>&1 | tee $(TEST_OUTFILE)
 
-### DOCS ###
+##@ DOCS
 
 docs-dependencies: .bundle
 
-.bundle:
+.bundle: ## Attempt to install bundle
 	if ! type bundle; then \
 		echo "Bundler not found. On Linux run 'sudo dnf install /usr/bin/bundle' to install it."; \
 		exit 1; \
@@ -48,7 +65,7 @@ docs-dependencies: .bundle
 
 	bundle config set --local path 'local/bundle'; bundle install
 
-docs: docs-dependencies docs-user-all-variants docs-dev
+docs: docs-dependencies docs-user-all-variants docs-dev ## Build documentation
 
 docs-user-all-variants:
 	cd docs_user; BUILD=upstream $(MAKE) html
@@ -72,5 +89,5 @@ docs-dev-open:
 docs-dev-watch:
 	cd docs_dev; $(MAKE) watch-html
 
-docs-clean:
+docs-clean:  ## Cleanup documentation
 	rm -r docs_build