Add help target to Makefile (#9531)

**What this PR does / why we need it**:

Add a help target to the Makefile. Only the main targets were added.

```
% make help

Usage:
  make <target>

Targets:
  help                                           Display this help and any documented user-facing targets. Other undocumented targets may be present in the Makefile.
  all                                            build all executables (loki, logcli, promtail, loki-canary)
  logcli                                         build logcli executable
  logcli-debug                                   build debug logcli executable
  logcli-image                                   build logcli docker image
  loki                                           build loki executable
  loki-debug                                     build loki debug executable
  loki-canary                                    build loki-canary executable
  helm-test                                      run helm tests
  helm-lint                                      run helm linter
  loki-querytee                                  build loki-querytee executable
  promtail                                       build promtail executable
  promtail-debug                                 build debug promtail executable
  loki-mixin                                     compile the loki mixin
  loki-mixin-check                               check the loki mixin is up to date
  lint                                           run linters
  test                                           run the unit tests
  clean                                          clean the generated files
  docker-driver                                  build the docker-driver executable
  fluent-bit-plugin                              build the fluent-bit plugin
  fluent-bit-image                               build the fluent-bit plugin docker image
  fluent-bit-push                                push the fluent-bit plugin docker image
  fluentd-plugin                                 build the fluentd plugin
  fluentd-plugin-push                            push the fluentd plugin
  fluentd-image                                  build the fluentd docker image
  fluentd-image-push                             push the fluentd docker image
  logstash-image                                 build the logstash image
  logstash-push                                  push the logstash image
  promtail-image                                 build the promtail docker image
  promtail-debug-image                           build the promtail debug docker image
  loki-image                                     build the loki docker image
  loki-debug-image                               build the debug loki docker image
  loki-canary-image                              build the loki canary docker image
  helm-test-image                                build the helm test image
  helm-test-push                                 push the helm test image
  logql-analyzer-image                           build the LogQL Analyzer image
  logql-analyzer-push                            push the LogQL Analyzer image
  build-image                                    build the docker build image
  build-image-push                               push the docker build image
  doc                                            Generates the config file documentation
  check-doc                                      Check the documentation files are up to date
```

**Checklist**
- [X] Reviewed the
[`CONTRIBUTING.md`](https://github.com/grafana/loki/blob/main/CONTRIBUTING.md)
guide (**required**)
- [ ] Documentation added
- [ ] Tests updated
- [ ] `CHANGELOG.md` updated
- [ ] Changes that require user attention or interaction to upgrade are
documented in `docs/sources/upgrading/_index.md`
- [ ] For Helm chart changes bump the Helm chart version in
`production/helm/loki/Chart.yaml` and update
`production/helm/loki/CHANGELOG.md` and
`production/helm/loki/README.md`. [Example
PR](d10549e3ec)

Signed-off-by: Michel Hollands <michel.hollands@grafana.com>

Makefile

@@ -1,3 +1,9 @@
+# Adapted from https://www.thapaliya.com/en/writings/well-documented-makefiles/
+.PHONY: help
+help: ## Display this help and any documented user-facing targets. Other undocumented targets may be present in the Makefile.
+help:
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make <target>\n\nTargets:\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  %-45s %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
 .DEFAULT_GOAL := all
 .PHONY: all images check-generated-files logcli loki loki-debug promtail promtail-debug loki-canary lint test clean yacc protos touch-protobuf-sources
 .PHONY: format check-format
@@ -114,7 +120,7 @@ binfmt:
 ################
 # Main Targets #
 ################
-all: promtail logcli loki loki-canary
+all: promtail logcli loki loki-canary ## build all executables (loki, logcli, promtail, loki-canary)
 
 # This is really a check for the CI to make sure generated files are built and checked in manually
 check-generated-files: yacc ragel fmt-proto protos clients/pkg/promtail/server/ui/assets_vfsdata.go
@@ -130,10 +136,10 @@ check-generated-files: yacc ragel fmt-proto protos clients/pkg/promtail/server/u
 # Logcli #
 ##########
 .PHONY: cmd/logcli/logcli
-logcli: cmd/logcli/logcli
-logcli-debug: cmd/logcli/logcli-debug
+logcli: cmd/logcli/logcli ## build logcli executable
+logcli-debug: cmd/logcli/logcli-debug ## build debug logcli executable
 
-logcli-image:
+logcli-image: ## build logcli docker image
 	$(SUDO) docker build -t $(IMAGE_PREFIX)/logcli:$(IMAGE_TAG) -f cmd/logcli/Dockerfile .
 
 cmd/logcli/logcli:
@@ -145,8 +151,8 @@ cmd/logcli/logcli-debug:
 # Loki #
 ########
 .PHONY: cmd/loki/loki cmd/loki/loki-debug
-loki: cmd/loki/loki
-loki-debug: cmd/loki/loki-debug
+loki: cmd/loki/loki ## build loki executable
+loki-debug: cmd/loki/loki-debug ## build loki debug executable
 
 cmd/loki/loki:
 	CGO_ENABLED=0 go build $(GO_FLAGS) -o $@ ./$(@D)
@@ -158,7 +164,7 @@ cmd/loki/loki-debug:
 # Loki-Canary #
 ###############
 .PHONY: cmd/loki-canary/loki-canary
-loki-canary: cmd/loki-canary/loki-canary
+loki-canary: cmd/loki-canary/loki-canary ## build loki-canary executable
 
 cmd/loki-canary/loki-canary:
 	CGO_ENABLED=0 go build $(GO_FLAGS) -o $@ ./$(@D)
@@ -167,20 +173,20 @@ cmd/loki-canary/loki-canary:
 # Helm #
 ###############
 .PHONY: production/helm/loki/src/helm-test/helm-test
-helm-test: production/helm/loki/src/helm-test/helm-test
+helm-test: production/helm/loki/src/helm-test/helm-test ## run helm tests
 
 # Package Helm tests but do not run them.
 production/helm/loki/src/helm-test/helm-test:
 	CGO_ENABLED=0 go test $(GO_FLAGS) --tags=helm_test -c -o $@ ./$(@D)
 
-helm-lint:
+helm-lint: ## run helm linter
 	$(MAKE) -BC production/helm/loki lint
 
 #################
 # Loki-QueryTee #
 #################
 .PHONY: cmd/querytee/querytee
-loki-querytee: cmd/querytee/querytee
+loki-querytee: cmd/querytee/querytee ## build loki-querytee executable
 
 cmd/querytee/querytee:
 	CGO_ENABLED=0 go build $(GO_FLAGS) -o $@ ./$(@D)
@@ -207,8 +213,8 @@ ifeq ($(PROMTAIL_JOURNAL_ENABLED), true)
 PROMTAIL_GO_TAGS = promtail_journal_enabled
 endif
 .PHONY: clients/cmd/promtail/promtail clients/cmd/promtail/promtail-debug
-promtail: clients/cmd/promtail/promtail
-promtail-debug: clients/cmd/promtail/promtail-debug
+promtail: clients/cmd/promtail/promtail ## build promtail executable
+promtail-debug: clients/cmd/promtail/promtail-debug ## build debug promtail executable
 
 promtail-clean-assets:
 	rm -rf clients/pkg/promtail/server/ui/assets_vfsdata.go
@@ -232,7 +238,7 @@ MIXIN_PATH := production/loki-mixin
 MIXIN_OUT_PATH := production/loki-mixin-compiled
 MIXIN_OUT_PATH_SSD := production/loki-mixin-compiled-ssd
 
-loki-mixin:
+loki-mixin: ## compile the loki mixin
 ifeq ($(BUILD_IN_CONTAINER),true)
 	$(SUDO) docker run $(RM) $(TTY) -i \
 		-v $(shell pwd):/src/loki$(MOUNT_FLAGS) \
@@ -247,7 +253,7 @@ else
 	@mixtool generate all --output-alerts $(MIXIN_OUT_PATH_SSD)/alerts.yaml --output-rules $(MIXIN_OUT_PATH_SSD)/rules.yaml --directory $(MIXIN_OUT_PATH_SSD)/dashboards ${MIXIN_PATH}/mixin-ssd.libsonnet
 endif
 
-loki-mixin-check: loki-mixin
+loki-mixin-check: loki-mixin ## check the loki mixin is up to date
 	@echo "Checking diff"
 	@git diff --exit-code -- $(MIXIN_OUT_PATH) || (echo "Please build mixin by running 'make loki-mixin'" && false)
 	@git diff --exit-code -- $(MIXIN_OUT_PATH_SSD) || (echo "Please build mixin by running 'make loki-mixin'" && false)
@@ -289,7 +295,7 @@ publish: packages
 
 # To run this efficiently on your workstation, run this from the root dir:
 # docker run --rm --tty -i -v $(pwd)/.cache:/go/cache -v $(pwd)/.pkg:/go/pkg -v $(pwd):/src/loki grafana/loki-build-image:0.24.1 lint
-lint:
+lint: ## run linters
 	go version
 	golangci-lint version
 	GO111MODULE=on golangci-lint run -v
@@ -299,7 +305,7 @@ lint:
 # Test #
 ########
 
-test: all
+test: all ## run the unit tests
 	$(GOTEST) -covermode=atomic -coverprofile=coverage.txt -p=4 ./... | sed "s:$$: ${DRONE_STEP_NAME} ${DRONE_SOURCE_BRANCH}:" | tee test_results.txt
 
 compare-coverage:
@@ -312,7 +318,7 @@ compare-coverage:
 clean-protos:
 	rm -rf $(PROTO_GOS)
 
-clean:
+clean: ## clean the generated files
 	rm -rf clients/cmd/promtail/promtail
 	rm -rf cmd/loki/loki
 	rm -rf cmd/logcli/logcli
@@ -421,7 +427,7 @@ define build-rootfs
 	docker rmi rootfsimage -f
 endef
 
-docker-driver: docker-driver-clean
+docker-driver: docker-driver-clean ## build the docker-driver executable
 	$(build-rootfs)
 	docker plugin create $(LOKI_DOCKER_DRIVER):$(PLUGIN_TAG)$(PLUGIN_ARCH) clients/cmd/docker-driver
 
@@ -454,13 +460,13 @@ docker-driver-clean:
 #####################
 # fluent-bit plugin #
 #####################
-fluent-bit-plugin:
+fluent-bit-plugin: ## build the fluent-bit plugin
 	go build $(DYN_GO_FLAGS) -buildmode=c-shared -o clients/cmd/fluent-bit/out_grafana_loki.so ./clients/cmd/fluent-bit/
 
-fluent-bit-image:
+fluent-bit-image: ## build the fluent-bit plugin docker image
 	$(SUDO) docker build -t $(IMAGE_PREFIX)/fluent-bit-plugin-loki:$(IMAGE_TAG) --build-arg LDFLAGS="-s -w $(GO_LDFLAGS)" -f clients/cmd/fluent-bit/Dockerfile .
 
-fluent-bit-push:
+fluent-bit-push: ## push the fluent-bit plugin docker image
 	$(SUDO) $(PUSH_OCI) $(IMAGE_PREFIX)/fluent-bit-plugin-loki:$(IMAGE_TAG)
 
 fluent-bit-test: LOKI_URL ?= http://localhost:3100/loki/api/
@@ -472,17 +478,17 @@ fluent-bit-test:
 ##################
 # fluentd plugin #
 ##################
-fluentd-plugin:
+fluentd-plugin: ## build the fluentd plugin
 	$(MAKE) -BC clients/cmd/fluentd $@
 
-fluentd-plugin-push:
+fluentd-plugin-push: ## push the fluentd plugin
 	$(MAKE) -BC clients/cmd/fluentd $@
 
-fluentd-image:
+fluentd-image: ## build the fluentd docker image
 	$(SUDO) docker build -t $(IMAGE_PREFIX)/fluent-plugin-loki:$(IMAGE_TAG) -f clients/cmd/fluentd/Dockerfile .
 
 fluentd-push:
-fluentd-image-push:
+fluentd-image-push: ## push the fluentd docker image
 	$(SUDO) $(PUSH_OCI) $(IMAGE_PREFIX)/fluent-plugin-loki:$(IMAGE_TAG)
 
 fluentd-test: LOKI_URL ?= http://loki:3100
@@ -492,7 +498,7 @@ fluentd-test:
 ##################
 # logstash plugin #
 ##################
-logstash-image:
+logstash-image: ## build the logstash image
 	$(SUDO) docker build -t $(IMAGE_PREFIX)/logstash-output-loki:$(IMAGE_TAG) -f clients/cmd/logstash/Dockerfile ./
 
 # Send 10 lines to the local Loki instance.
@@ -501,7 +507,7 @@ logstash-push-test-logs:
 	$(SUDO) docker run -e LOKI_URL="$(LOKI_URL)" -v `pwd`/clients/cmd/logstash/loki-test.conf:/home/logstash/loki.conf --rm \
 		$(IMAGE_PREFIX)/logstash-output-loki:$(IMAGE_TAG) -f loki.conf
 
-logstash-push:
+logstash-push: ## push the logstash image
 	$(SUDO) $(PUSH_OCI) $(IMAGE_PREFIX)/logstash-output-loki:$(IMAGE_TAG)
 
 # Enter an env already configure to build and test logstash output plugin.
@@ -543,41 +549,41 @@ define push-image
 endef
 
 # promtail
-promtail-image:
+promtail-image: ## build the promtail docker image
 	$(SUDO) docker build -t $(IMAGE_PREFIX)/promtail:$(IMAGE_TAG) -f clients/cmd/promtail/Dockerfile .
 promtail-image-cross:
 	$(SUDO) $(BUILD_OCI) -t $(IMAGE_PREFIX)/promtail:$(IMAGE_TAG) -f clients/cmd/promtail/Dockerfile.cross .
 
 promtail-debug-image: OCI_PLATFORMS=
-promtail-debug-image:
+promtail-debug-image: ## build the promtail debug docker image
 	$(SUDO) $(BUILD_OCI) -t $(IMAGE_PREFIX)/promtail:$(IMAGE_TAG)-debug -f clients/cmd/promtail/Dockerfile.debug .
 
 promtail-push: promtail-image-cross
 	$(call push-image,promtail)
 
 # loki
-loki-image:
+loki-image: ## build the loki docker image
 	$(SUDO) docker build -t $(IMAGE_PREFIX)/loki:$(IMAGE_TAG) -f cmd/loki/Dockerfile .
 loki-image-cross:
 	$(SUDO) $(BUILD_OCI) -t $(IMAGE_PREFIX)/loki:$(IMAGE_TAG) -f cmd/loki/Dockerfile.cross .
 
 loki-debug-image: OCI_PLATFORMS=
-loki-debug-image:
+loki-debug-image: ## build the debug loki docker image
 	$(SUDO) $(BUILD_OCI) -t $(IMAGE_PREFIX)/loki:$(IMAGE_TAG)-debug -f cmd/loki/Dockerfile.debug .
 
 loki-push: loki-image-cross
 	$(call push-image,loki)
 
 # loki-canary
-loki-canary-image:
+loki-canary-image: ## build the loki canary docker image
 	$(SUDO) docker build -t $(IMAGE_PREFIX)/loki-canary:$(IMAGE_TAG) -f cmd/loki-canary/Dockerfile .
 loki-canary-image-cross:
 	$(SUDO) $(BUILD_OCI) -t $(IMAGE_PREFIX)/loki-canary:$(IMAGE_TAG) -f cmd/loki-canary/Dockerfile.cross .
 loki-canary-push: loki-canary-image-cross
 	$(SUDO) $(PUSH_OCI) $(IMAGE_PREFIX)/loki-canary:$(IMAGE_TAG)
-helm-test-image:
+helm-test-image: ## build the helm test image
 	$(SUDO) docker build -t $(IMAGE_PREFIX)/loki-helm-test:$(IMAGE_TAG) -f production/helm/loki/src/helm-test/Dockerfile .
-helm-test-push: helm-test-image
+helm-test-push: helm-test-image ## push the helm test image
 	$(SUDO) $(PUSH_OCI) $(IMAGE_PREFIX)/loki-helm-test:$(IMAGE_TAG)
 
 # loki-querytee
@@ -593,17 +599,17 @@ migrate-image:
 	$(SUDO) docker build -t $(IMAGE_PREFIX)/loki-migrate:$(IMAGE_TAG) -f cmd/migrate/Dockerfile .
 
 # LogQL Analyzer
-logql-analyzer-image:
+logql-analyzer-image: ## build the LogQL Analyzer image
 	$(SUDO) docker build -t $(IMAGE_PREFIX)/logql-analyzer:$(IMAGE_TAG) -f cmd/logql-analyzer/Dockerfile .
-logql-analyzer-push: logql-analyzer-image
+logql-analyzer-push: logql-analyzer-image ## push the LogQL Analyzer image
 	$(call push-image,logql-analyzer)
 
 
 # build-image (only amd64)
 build-image: OCI_PLATFORMS=
-build-image:
+build-image: ## build the docker build image
 	$(SUDO) $(BUILD_OCI) -t $(IMAGE_PREFIX)/loki-build-image:$(IMAGE_TAG) ./loki-build-image
-build-image-push: build-image
+build-image-push: build-image ## push the docker build image
 ifneq (,$(findstring WIP,$(IMAGE_TAG)))
 	@echo "Cannot push a WIP image, commit changes first"; \
 	false;