build(Makefile): Help notification stub started.

Makefile

@@ -10,29 +10,44 @@ export db ?= -cf
 export DEV_PORT_HTTP
 export DEV_PORT_HTTPS
 
+# HELP HEADER START
+# To see the definition of all available targets, take a look into the Makefile.
+# Targets starting with '--' are not meant to be directly called.
+# If you want to do so anyway please use 'make -- [--target]' to not
+# have '[--target]' to be treated as option to 'make'.
+# 
+# 
+# Targets meant to be used by humans are:
+# HELP HEADER END
+
 ###########################
 ##### GENERAL TARGETS #####
 
 .PHONY: help
+# HELP: print out this help message
 help:
 	@echo "Nothing to see here, go away"
 
 .PHONY: all
+# HELP: unfinished
 all:
 	@echo "TODO"
 
 .PHONY: clean
+# HELP: remove all compilation results in the directory but leave containers and images unharmed
 clean:
 	rm -rf node_modules .npm .cache assets/icons assets/favicons static well-known 
 	rm -rf .stack .stack-work .stack-work-build .stack-work-run .stack-work-test .stack-work-doc
 	rm -rf bin/ .Dockerfile .dev-port-http .dev-port-https
 .PHONY: clean-all
+# HELP: like clean but with container and image prune
 clean-all: clean
 	$(CONTAINER_COMMAND) system prune --all --force --volumes
 	$(CONTAINER_COMMAND) image prune --all --force
 	$(CONTAINER_COMMAND) volume prune --force
 
 .PHONY: release
+# HELP: unfinished
 release:
 	./.gitlab-ci/version.pl -changelog CHANGELOG.md
 	git add CHANGELOG.md
@@ -56,6 +71,7 @@ release:
 ##### UNIFIED FRONTEND/BACKEND TARGETS #####
 
 .PHONY: serve
+# HELP: serve frontend, backend, and database
 serve: CONTAINER_INTERACTIVE=-it
 serve:
 	$(MAKE) serve-database &
@@ -63,12 +79,15 @@ serve:
 	$(MAKE) serve-backend
 
 .PHONY: compile
+# HELP: compile frontend and backend
 compile: compile-frontend compile-backend
 
 .PHONY: lint
+# HELP: lint frontend and backend
 lint: lint-frontend lint-backend
 
 .PHONY: test
+# HELP: test frontend, backend, and check internationalization
 test: test-frontend test-backend i18n-check
 
 ##### UNIFIED FRONTEND/BACKEND TARGETS #####
@@ -85,11 +104,13 @@ test: test-frontend test-backend i18n-check
 .PHONY: --%-frontend
 --%-frontend: --containerized---frontend-dependencies-frontend;
 
+# HELP(compile-frontend): compile frontend
 .PHONY: --compile-frontend
 --compile-frontend: --frontend-dependencies
 	npx -- webpack --progress $(WATCH)
 
 .PHONY: serve-frontend
+# HELP: serve frontend (watch file changes)
 serve-frontend: CONTAINER_INTERACTIVE=-it
 serve-frontend:
 	$(MAKE) -- --containerized---compile-frontend WATCH=--watch
@@ -98,11 +119,13 @@ serve-frontend:
 # --serve-frontend: WATCH=--watch
 # --serve-frontend: --compile-frontend;
 
+# HELP(lint-frontend): lint frontend
 .PHONY: --lint-frontend
 --lint-frontend: eslint.config.js
 	npx -- eslint frontend/src $(FIX)
 	@echo Hooray! There are no hints.
 
+# HELP(test-frontend): test frontend
 .PHONY: --test-frontend
 --test-frontend: karma.conf.cjs
 	@echo Karma frontend tests are currently broken after npm update and have therefor been temporarily disabled.
@@ -153,6 +176,7 @@ well-known: node_modules assets
 --%-prod-backend: --image-build --containerized-%-backend;
 
 .PHONY: serve-backend
+# HELP: serve backend
 serve-backend: CONTAINER_INTERACTIVE=-it
 serve-backend:
 	DEV_PORT_HTTP=`docker/backend/dev_port.pl 3000 | tee .dev-port-http`; \
@@ -164,19 +188,23 @@ serve-backend:
 	DEV_PORT_HTTPS=`cat .dev-port-https`; \
 	./start.sh
 
+# HELP(compile-backend): compile backend
 .PHONY: --compile-backend
 --compile-backend:
 	stack build --fast --profile --library-profiling --executable-profiling --flag uniworx:-library-only --local-bin-path $$(pwd)/bin $(stackopts)
 
+# HELP(lint-backend): lint backend
 .PHONY: --lint-backend
 --lint-backend:
 	stack build --test --fast --flag uniworx:library-only uniworx:test:hlint $(stackopts)
 
+# HELP(test-backend): test backend
 .PHONY: --test-backend
 --test-backend:
 	stack build --test --coverage --fast --flag uniworx:library-only $(stackopts)
 
 .PHONY: serve-database
+# HELP: serve database
 serve-database: CONTAINER_INTERACTIVE=-it
 serve-database: --containerized-database
 
@@ -230,6 +258,7 @@ serve-database: --containerized-database
 	$(MAKE) -- --image-run-$*-backend 
 
 .PHONY: image-rebuild
+# HELP: rebuild the stated docker image (frontend, backend, database instead of %)
 image-rebuild-%:
 	$(MAKE) -- --image-build FRADRIVE_SERVICE=$* NO_CACHE=--no-cache
 .PHONY: --image-build
@@ -259,6 +288,7 @@ image-rebuild-%:
 
 
 .PHONY: i18n-check
+# HELP: check internationalization
 i18n-check: --image-run---i18n-check
 .PHONY: --i18n-check
 --i18n-check:

utils/makehelp.pl

@@ -0,0 +1,40 @@
+#!/usr/bin/env perl
+
+use strict;
+use warnings;
+
+my %msg = ();
+my @start = ();
+
+READ: while(<>) {
+  if(m/^# HELP HEADER START/) {
+    while(<>) {
+      next READ if m/^# HELP HEADER END/;
+      if(m/# (.*)/) {
+        push @start, $1
+      } else {
+        die "$0: Invalid HELP HEADER section in Makefile!\n";
+      }
+    }
+    next READ
+  }
+  if(m/# HELP((?:\([^\(\)]+\))?):\s*(.*)/) {
+    my ($target, $message) = ($1, $2);
+    if($target=~m/\((.*)\)/) {
+      $target = $1;
+    } else {
+      my $line = <>;
+      die "$0: Unexpected end of file, target expected!\n" if not defined $line;
+      $line=~m/^([^:]+):/ or die "$0: HELP marker expects target but no target found!\n";
+      $target = $1
+    }
+    $msg{$target} .= $message
+  }
+}
+
+print "$_\n" for @start;
+print "\n" if @start;
+for my $tar(sort keys %msg) {
+  print "$tar\n  $msg{$tar}\n\n"
+}
+