Add Makefile documentation (#373)

Add help texts for Make targets and generate output for make help. Signed-off-by: ddelange <[email protected]> Signed-off-by: Christian Kadner <[email protected]> Co-authored-by: Christian Kadner <[email protected]>
kserve · Aug 15, 2023 · 27ac6c9 · 27ac6c9
1 parent 4c1edc3
commit 27ac6c9
Show file tree

Hide file tree

Showing 2 changed files with 46 additions and 40 deletions.
diff --git a/Makefile b/Makefile
@@ -51,70 +51,75 @@ GOBIN=$(shell go env GOBIN)
 endif
 
 .PHONY: all
+## Alias for `manager`
 all: manager
 
-# Run unit tests, requires kubebuilder, etcd, kube-apiserver, envtest
 .PHONY: test
+## Run unit tests (Requires kubebuilder, etcd, kube-apiserver, envtest)
 test:
 	KUBEBUILDER_ASSETS="$$(setup-envtest use $(KUBERNETES_VERSION) -p path)" \
 	KUBEBUILDER_CONTROLPLANE_STOP_TIMEOUT=120s \
 	go test -coverprofile cover.out `go list ./... | grep -v fvt`
 
-# Run fvt tests. This requires an etcd, kubernetes connection, and model serving installation. Ginkgo CLI is used to run them in parallel
 .PHONY: fvt
+## Run FVT tests (Requires ModelMesh Serving deployment and GinkGo CLI)
 fvt:
 	ginkgo -v -procs=2 --fail-fast fvt/predictor fvt/scaleToZero fvt/storage fvt/hpa --timeout=50m
 
-# Command to regenerate the grpc go files from the proto files
-.PHONY: fvt-protoc
-fvt-protoc:
+.PHONY: codegen-fvt
+## Regenerate grpc code stubs for FVT
+codegen-fvt:
 	rm -rf fvt/generated
 	protoc -I=fvt/proto --go_out=plugins=grpc:. --go_opt=module=github.com/kserve/modelmesh-serving $(shell find fvt/proto -iname "*.proto")
 
 .PHONY: fvt-with-deploy
-fvt-with-deploy: oc-login deploy-release-dev-mode fvt
+## Alias for `oc-login, deploy-release-fvt, fvt`
+fvt-with-deploy: oc-login deploy-release-fvt fvt
 
 .PHONY: oc-login
+## Login to OCP cluster
 oc-login:
 	oc login --token=${OCP_TOKEN} --server=https://${OCP_ADDRESS} --insecure-skip-tls-verify=true
 
-# Build manager binary
 .PHONY: manager
+## Build `manager` binary
 manager: generate fmt
 	go build -o bin/manager main.go
 
-# Run against the configured Kubernetes cluster in ~/.kube/config
 .PHONY: start
+## Run against a Kubernetes cluster
 start: generate fmt manifests
 	go run ./main.go
 
-# Install CRDs into a cluster
 .PHONY: install
+## Install CRDs into a Kubernetes cluster
 install: manifests
 	kustomize build config/crd | kubectl apply -f -
 
-# Uninstall CRDs from a cluster
 .PHONY: uninstall
+## Uninstall CRDs from a Kubernetes cluster
 uninstall: manifests
 	kustomize build config/crd | kubectl delete -f -
 
-# Deploy controller in the configured Kubernetes cluster in ~/.kube/config
 .PHONY: deploy
+## Deploy manifests to Kubernetes cluster
 deploy: manifests
 	cd config/manager && kustomize edit set image controller=${IMG}
 	kustomize build config/default | kubectl apply -f -
 
-# artifactory creds set via env var
 .PHONY: deploy-release
+## Deploy release (artifactory creds set via env var)
 deploy-release:
 	./scripts/install.sh --namespace ${NAMESPACE} --install-config-path config
 
-.PHONY: deploy-release-dev-mode
-deploy-release-dev-mode:
+.PHONY: deploy-release-dev
+## Deploy release in dev mode (artifactory creds set via env var)
+deploy-release-dev:
 	./scripts/install.sh --namespace ${NAMESPACE} --install-config-path config --dev-mode-logging
 
-.PHONY: deploy-release-dev-mode-fvt
-deploy-release-dev-mode-fvt:
+.PHONY: deploy-release-fvt
+## Deploy release in dev mode for FVT tests
+deploy-release-fvt:
 ifdef MODELMESH_SERVING_IMAGE
 	$(eval extra_options += --modelmesh-serving-image ${MODELMESH_SERVING_IMAGE})
 endif
@@ -123,12 +128,13 @@ ifdef NAMESPACE_SCOPE_MODE
 endif
 	./scripts/install.sh --namespace ${NAMESPACE} --install-config-path config --dev-mode-logging --fvt ${extra_options}
 
-.PHONY: delete
-delete: oc-login
+.PHONY: undeploy-release
+## Undeploy the ModelMesh Serving installation
+undeploy-release:
 	./scripts/delete.sh --namespace ${NAMESPACE} --local-config-path config
 
-# Generate manifests e.g. CRD, RBAC etc.
 .PHONY: manifests
+## Generate manifests e.g. CRD, RBAC etc.
 manifests: controller-gen
 		# NOTE: We're currently copying the CRD manifests from KServe rather than using this target to regenerate those
 		# that are common (all apart from predictors) because the formatting ends up different depending on the version
@@ -141,50 +147,44 @@ manifests: controller-gen
 	rm -f ./config/crd/bases/serving.kserve.io_trainedmodels.yaml
 	pre-commit run --all-files prettier > /dev/null || true
 
-# Run go fmt against code
 .PHONY: fmt
+## Auto-format source code and report code-style violations (lint)
 fmt:
 	./scripts/fmt.sh || (echo "Linter failed: $$?"; git status; exit 1)
 
-# Generate code
 .PHONY: generate
+## Generate code
 generate: controller-gen
 	$(CONTROLLER_GEN) object:headerFile="scripts/controller-gen-header.go.tmpl" paths="./..."
 	pre-commit run --all-files prettier > /dev/null || true
 
-# Build the final runtime docker image
 .PHONY: build
+## Build runtime container image
 build: build.develop
 	./scripts/build_docker.sh --target runtime --engine $(ENGINE)
 
-# Build the develop docker image
 .PHONY: build.develop
+## Build developer container image
 build.develop:
 	./scripts/build_devimage.sh $(ENGINE)
 
-# Start a terminal session in the develop docker container
 .PHONY: develop
+## Run interactive shell inside developer container
 develop: build.develop
 	./scripts/develop.sh
 
-# Run make commands from within the develop docker container
-# For example, `make run fmt` will execute `make fmt` within the docker container
 .PHONY: run
+## Run make target inside developer container (e.g. `make run fmt`)
 run: build.develop
 	./scripts/develop.sh make $(RUN_ARGS)
 
-# Build the docker image
-.PHONY: docker-build
-docker-build: build
-
-# Push the docker image
-.PHONY: docker-push
-docker-push:
+.PHONY: push
+## Push the controller runtime image
+push:
 	docker push ${IMG}
 
-# find or download controller-gen
-# download controller-gen if necessary
 .PHONY: controller-gen
+## Find or download controller-gen
 controller-gen:
 ifeq (, $(shell which controller-gen))
 	@{ \
@@ -196,15 +196,21 @@ else
 CONTROLLER_GEN=$(shell which controller-gen)
 endif
 
-# Model Mesh gRPC codegen
-.PHONY: mmesh-codegen
-mmesh-codegen:
+.PHONY: codegen
+## Generate gRPC code stubs (protoc)
+codegen:
 	protoc -I proto/ --go_out=plugins=grpc:generated/ $(PROTO_FILES)
 
-# Check markdown files for invalid links
 .PHONY: check-doc-links
+## Check markdown files for invalid links
 check-doc-links:
 	@python3 scripts/verify_doc_links.py && echo "$@: OK"
 
+.DEFAULT_GOAL := help
+.PHONY: help
+## Print Makefile documentation
+help:
+	@perl -0 -nle 'printf("\033[36m  %-20s\033[0m %s\n", "$$2", "$$1") while m/^##\s*([^\r\n]+)\n^([\w.-]+):[^=]/gm' $(MAKEFILE_LIST) | sort
+
 # Override targets if they are included in RUN_ARGs so it doesn't run them twice
 $(eval $(RUN_ARGS):;@:)
diff --git a/docs/developer.md b/docs/developer.md
@@ -67,7 +67,7 @@ If you have a custom controller image in your repository, set `MODELMESH_SERVING
 ```shell
 NAMESPACE=modelmesh-serving \
 MODELMESH_SERVING_IMAGE=quay.io/$org/modelmesh-controller:custom \
-make deploy-release-dev-mode-fvt
+make deploy-release-fvt
 ```
 
 ## Building the developer image