Docs: Document Makefile (#19720)

* Document Makefile

* Fix review comments

* Rename group to Services

* Fix review comments

Makefile

@@ -1,6 +1,10 @@
+## This is a self-documented Makefile. For usage information, run `make help`:
+##
+## For more information, refer to https://suva.sh/posts/well-documented-makefiles/
+
 -include local/Makefile
 
-.PHONY: all deps-go deps-js deps build-go build-server build-cli build-js build build-docker-dev build-docker-full lint-go gosec revive golangci-lint go-vet test-go test-js test run clean devenv devenv-down revive-alerting
+.PHONY: all deps-go deps-js deps build-go build-server build-cli build-js build build-docker-dev build-docker-full lint-go gosec revive golangci-lint go-vet test-go test-js test run clean devenv devenv-down revive-alerting help
 
 GO = GO111MODULE=on go
 GO_FILES ?= ./pkg/...
@@ -8,76 +12,63 @@ SH_FILES ?= $(shell find ./scripts -name *.sh)
 
 all: deps build
 
-deps-go:
+##@ Dependencies
+
+deps-go: ## Install backend dependencies.
 	$(GO) run build.go setup
 
-deps-js: node_modules
+deps-js: node_modules ## Install frontend dependencies.
 
-deps: deps-js
+deps: deps-js ## Install all dependencies.
 
-build-go:
-	@echo "build go files"
-	$(GO) run build.go build
-
-build-server:
-	@echo "build server"
-	$(GO) run build.go build-server
-
-build-cli:
-	@echo "build in CI environment"
-	$(GO) run build.go build-cli
-
-build-js:
-	@echo "build frontend"
-	yarn run build
-
-build: build-go build-js
-
-build-docker-dev:
-	@echo "build development container"
-	@echo "\033[92mInfo:\033[0m the frontend code is expected to be built already."
-	$(GO) run build.go -goos linux -pkg-arch amd64 ${OPT} build pkg-archive latest
-	cp dist/grafana-latest.linux-x64.tar.gz packaging/docker
-	cd packaging/docker && docker build --tag grafana/grafana:dev .
-
-build-docker-full:
-	@echo "build docker container"
-	docker build --tag grafana/grafana:dev .
-
-test-go:
-	@echo "test backend"
-	$(GO) test -v ./pkg/...
-
-test-js:
-	@echo "test frontend"
-	yarn test
-
-test: test-go test-js
-
-clean:
-	@echo "cleaning"
-	rm -rf node_modules
-	rm -rf public/build
-
-node_modules: package.json yarn.lock
+node_modules: package.json yarn.lock ## Install node modules.
 	@echo "install frontend dependencies"
 	yarn install --pure-lockfile --no-progress
 
-scripts/go/bin/revive: scripts/go/go.mod
-	@cd scripts/go; \
-	$(GO) build -o ./bin/revive github.com/mgechev/revive
+##@ Building
 
-scripts/go/bin/gosec: scripts/go/go.mod
-	@cd scripts/go; \
-	$(GO) build -o ./bin/gosec github.com/securego/gosec/cmd/gosec
+build-go: ## Build all Go binaries.
+	@echo "build go files"
+	$(GO) run build.go build
+
+build-server: ## Build Grafana server.
+	@echo "build server"
+	$(GO) run build.go build-server
+
+build-cli: ## Build Grafana CLI application.
+	@echo "build in CI environment"
+	$(GO) run build.go build-cli
+
+build-js: ## Build frontend assets.
+	@echo "build frontend"
+	yarn run build
+
+build: build-go build-js ## Build backend and frontend.
 
 scripts/go/bin/bra: scripts/go/go.mod
 	@cd scripts/go; \
 	$(GO) build -o ./bin/bra github.com/unknwon/bra
 
-scripts/go/bin/golangci-lint: scripts/go/go.mod
+run: scripts/go/bin/bra ## Build and run web server on filesystem changes.
+	@GO111MODULE=on scripts/go/bin/bra run
+
+##@ Testing
+
+test-go: ## Run tests for backend.
+	@echo "test backend"
+	$(GO) test -v ./pkg/...
+
+test-js: ## Run tests for frontend.
+	@echo "test frontend"
+	yarn test
+
+test: test-go test-js ## Run all tests.
+
+##@ Linting
+
+scripts/go/bin/revive: scripts/go/go.mod
 	@cd scripts/go; \
-	$(GO) build -o ./bin/golangci-lint github.com/golangci/golangci-lint/cmd/golangci-lint
+	$(GO) build -o ./bin/revive github.com/mgechev/revive
 
 revive: scripts/go/bin/revive
 	@echo "lint via revive"
@@ -92,6 +83,20 @@ revive-alerting: scripts/go/bin/revive
 		-formatter stylish \
 		./pkg/services/alerting/...
 
+scripts/go/bin/golangci-lint: scripts/go/go.mod
+	@cd scripts/go; \
+	$(GO) build -o ./bin/golangci-lint github.com/golangci/golangci-lint/cmd/golangci-lint
+
+golangci-lint: scripts/go/bin/golangci-lint
+	@echo "lint via golangci-lint"
+	@scripts/go/bin/golangci-lint run \
+		--config ./scripts/go/configs/.golangci.yml \
+		$(GO_FILES)
+
+scripts/go/bin/gosec: scripts/go/go.mod
+	@cd scripts/go; \
+	$(GO) build -o ./bin/gosec github.com/securego/gosec/cmd/gosec
+
 # TODO recheck the rules and leave only necessary exclusions
 gosec: scripts/go/bin/gosec
 	@echo "lint via gosec"
@@ -100,25 +105,31 @@ gosec: scripts/go/bin/gosec
 		-conf=./scripts/go/configs/gosec.json \
 		$(GO_FILES)
 
-golangci-lint: scripts/go/bin/golangci-lint
-	@echo "lint via golangci-lint"
-	@scripts/go/bin/golangci-lint run \
-		--config ./scripts/go/configs/.golangci.yml \
-		$(GO_FILES)
-
 go-vet:
 	@echo "lint via go vet"
 	@$(GO) vet $(GO_FILES)
 
-lint-go: go-vet golangci-lint revive revive-alerting gosec
+lint-go: go-vet golangci-lint revive revive-alerting gosec ## Run all code checks for backend.
 
 # with disabled SC1071 we are ignored some TCL,Expect `/usr/bin/env expect` scripts
-shellcheck: $(SH_FILES)
+shellcheck: $(SH_FILES) ## Run checks for shell scripts.
 	@docker run --rm -v "$$PWD:/mnt" koalaman/shellcheck:stable \
 	$(SH_FILES) -e SC1071 -e SC2162
 
-run: scripts/go/bin/bra
-	@GO111MODULE=on scripts/go/bin/bra run
+##@ Docker
+
+build-docker-dev: ## Build Docker image for development (fast).
+	@echo "build development container"
+	@echo "\033[92mInfo:\033[0m the frontend code is expected to be built already."
+	$(GO) run build.go -goos linux -pkg-arch amd64 ${OPT} build pkg-archive latest
+	cp dist/grafana-latest.linux-x64.tar.gz packaging/docker
+	cd packaging/docker && docker build --tag grafana/grafana:dev .
+
+build-docker-full: ## Build Docker image for development.
+	@echo "build docker container"
+	docker build --tag grafana/grafana:dev .
+
+##@ Services
 
 # create docker-compose file with provided sources and start them
 # example: make devenv sources=postgres,openldap
@@ -126,7 +137,7 @@ ifeq ($(sources),)
 devenv:
 	@printf 'You have to define sources for this command \nexample: make devenv sources=postgres,openldap\n'
 else
-devenv: devenv-down
+devenv: devenv-down ## Start optional services, e.g. postgres, prometheus, and elasticsearch.
 	$(eval targets := $(shell echo '$(sources)' | tr "," " "))
 
 	@cd devenv; \
@@ -137,8 +148,17 @@ devenv: devenv-down
 	docker-compose up -d --build
 endif
 
-# drop down the envs
-devenv-down:
+devenv-down: ## Stop optional services.
 	@cd devenv; \
 	test -f docker-compose.yaml && \
 	docker-compose down || exit 0;
+
+##@ Helpers
+
+clean: ## Clean up intermediate build artifacts.
+	@echo "cleaning"
+	rm -rf node_modules
+	rm -rf public/build
+
+help: ## Display this help.
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)