Makefile: add a help target

Makefile.local

@@ -10,86 +10,87 @@ SETTINGS_PROD = swh.web.settings.production
 yarn-install: package.json
 	$(YARN) install --frozen-lockfile
 
+
 .PHONY: build-webpack-dev
-build-webpack-dev: yarn-install
+build-webpack-dev: yarn-install ## Build frontend assets with webpack
 	$(YARN) build-dev
 
 .PHONY: build-webpack-test
-build-webpack-test: yarn-install
+build-webpack-test: yarn-install ## | same with coverage activated
 	$(YARN) build-test
 
 .PHONY: build-webpack-dev-no-verbose
-build-webpack-dev-no-verbose: yarn-install
+build-webpack-dev-no-verbose: yarn-install ## | same as above without any output
 	$(YARN) build-dev >/dev/null
 
 .PHONY: build-webpack-prod
-build-webpack-prod: yarn-install
+build-webpack-prod: yarn-install ## | build assets minified and with mappings for sentry
 	$(YARN) build
 
 .PHONY: run-migrations-dev
-run-migrations-dev:
+run-migrations-dev: ## Run django db migration (dev: swh.web.settings.development)
 	python3 swh/web/manage.py rename_app --settings=$(SETTINGS_DEV) swh_web_common swh_web_save_code_now
 	python3 swh/web/manage.py migrate --settings=$(SETTINGS_DEV) -v0
 
 .PHONY: run-migrations-prod
-run-migrations-prod:
+run-migrations-prod: ## | same with prod settings (swh.web.settings.production)
 	django-admin rename_app --settings=$(SETTINGS_PROD) swh_web_common swh_web_save_code_now
 	django-admin migrate --settings=$(SETTINGS_PROD) -v0
 
 .PHONY: run-migrations-test
-run-migrations-test:
+run-migrations-test: ## | same with test settings (swh.web.settings.tests)
 	rm -f swh-web-test*.sqlite3*
 	django-admin migrate --settings=$(SETTINGS_TEST) -v0
 
-add-users-test: run-migrations-test
+add-users-test: run-migrations-test ## Create default django users (tests settings)
 	cat swh/web/tests/create_test_admin.py | django-admin shell --settings=$(SETTINGS_TEST)
 	cat swh/web/tests/create_test_users.py | django-admin shell --settings=$(SETTINGS_TEST)
 
-add-users-dev: run-migrations-dev
+add-users-dev: run-migrations-dev ## | same, using dev settings
 	cat swh/web/tests/create_test_admin.py | django-admin shell --settings=$(SETTINGS_DEV)
 	cat swh/web/tests/create_test_users.py | django-admin shell --settings=$(SETTINGS_DEV)
 
-add-users-prod: run-migrations-prod
+add-users-prod: run-migrations-prod ## | same, using prod settings
 	cat swh/web/tests/create_test_admin.py | django-admin shell --settings=$(SETTINGS_PROD)
 	cat swh/web/tests/create_test_users.py | django-admin shell --settings=$(SETTINGS_PROD)
 
 .PHONY: clear-memcached
-clear-memcached:
+clear-memcached: ## Clear locally running memcache (on localhost:1211)
 	echo "flush_all" | nc -q 2 localhost 11211 2>/dev/null
 
-run-django-webpack-devserver: add-users-dev yarn-install
+run-django-webpack-devserver: add-users-dev yarn-install ## Start webpack and django servers using dev settings (frontend and backend parts of the webapp get automatically reloaded when source files are modified)
 	bash -c "trap 'trap - SIGINT SIGTERM ERR EXIT && \
 	# ensure all child processes will be killed by PGID when exiting \
 	ps -o pgid= $$$$ | grep -o [0-9]* | xargs pkill -g' SIGINT SIGTERM ERR EXIT; \
 	$(YARN) start-dev & sleep 10 && cd swh/web && \
 	python3 manage.py runserver --nostatic --settings=$(SETTINGS_DEV) || exit 1"
 
-run-django-webpack-dev: build-webpack-dev add-users-dev
+run-django-webpack-dev: build-webpack-dev add-users-dev ## Build assets & start django from src using dev settings
 	python3 swh/web/manage.py runserver --nostatic --settings=$(SETTINGS_DEV)
 
-run-django-webpack-prod: build-webpack-prod add-users-prod clear-memcached
+run-django-webpack-prod: build-webpack-prod add-users-prod clear-memcached ## | same with prod settings
 	python3 swh/web/manage.py runserver --nostatic --settings=$(SETTINGS_PROD)
 
-run-django-server-dev: add-users-dev
+run-django-server-dev: add-users-dev ## Start django from src using dev settings
 	python3 swh/web/manage.py runserver --nostatic --settings=$(SETTINGS_DEV)
 
-run-django-server-prod: add-users-prod clear-memcached
+run-django-server-prod: add-users-prod clear-memcached ## | same with prod settings
 	python3 swh/web/manage.py runserver --nostatic --settings=$(SETTINGS_PROD)
 
-run-gunicorn-server: add-users-prod clear-memcached
+run-gunicorn-server: add-users-prod clear-memcached ## Clear memcache and start django from gunicorn (prod settings)
 	DJANGO_SETTINGS_MODULE=$(SETTINGS_PROD) \
 	gunicorn --bind 127.0.0.1:5004 \
 	--threads 2 \
 	--workers 2 'django.core.wsgi:get_wsgi_application()'
 
-run-django-webpack-memory-storages: build-webpack-dev add-users-test
+run-django-webpack-memory-storages: build-webpack-dev add-users-test ## Start django from tests settings (using in-memory storages)
 	python3 swh/web/manage.py runserver --nostatic --settings=$(SETTINGS_TEST)
 
-run-mirror-demo: build-webpack-dev add-users-test
+run-mirror-demo: build-webpack-dev add-users-test ## Start django from tests config using a mirror setup
 	SWH_CONFIG_FILENAME=$$PWD/mirror_demo/config.yml python3 swh/web/manage.py runserver \
 	--nostatic --settings=$(SETTINGS_TEST)
 
-test-full:
+test-full: ## Run all python tests
 	$(TEST) $(TESTFULL_FLAGS) $(TEST_DIRS)
 
 .PHONY: test-frontend-cmd
@@ -101,10 +102,10 @@ test-frontend-cmd: build-webpack-test add-users-test
 	$(YARN) mochawesome && $(YARN) nyc-report"
 
 test-frontend: export CYPRESS_SKIP_SLOW_TESTS=1
-test-frontend: test-frontend-cmd
+test-frontend: test-frontend-cmd ## Run cypress non-slow tests (no GUI)
 
 test-frontend-full: export CYPRESS_SKIP_SLOW_TESTS=0
-test-frontend-full: test-frontend-cmd
+test-frontend-full: test-frontend-cmd ## | same, including slow tests
 
 .PHONY: test-frontend-ui-cmd
 test-frontend-ui-cmd: add-users-test yarn-install
@@ -118,15 +119,22 @@ test-frontend-ui-cmd: add-users-test yarn-install
 	sleep 10 && $(YARN) run cypress open"
 
 test-frontend-ui: export CYPRESS_SKIP_SLOW_TESTS=1
-test-frontend-ui: test-frontend-ui-cmd
+test-frontend-ui: test-frontend-ui-cmd ## Run cypress non-slow tests in a browser (GUI)
 
 test-frontend-full-ui: export CYPRESS_SKIP_SLOW_TESTS=0
-test-frontend-full-ui: test-frontend-ui-cmd
+test-frontend-full-ui: test-frontend-ui-cmd # \ same, including slow tests
 
 
 # Override default rule to make sure DJANGO env var is properly set. It
 # *should* work without any override thanks to the mypy django-stubs plugin,
 # but it currently doesn't; see
 # https://github.com/typeddjango/django-stubs/issues/166
-check-mypy:
+check-mypy: ## Run mypy (with properly set env vars for django)
 	DJANGO_SETTINGS_MODULE=$(SETTINGS_DEV) $(MYPY) $(MYPYFLAGS) swh
+
+
+.PHONY: help
+help:
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sed -e s/Makefile.local:// | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+.DEFAULT_GOAL := help