docs: add 'make help', update tooltips, rename some targets (#553)

* update makefile target documentation for consistency * group targets into categories * rename `make testdaemon-image` to `make daemon` * rename `make daemon` to `make daemon-release` * add new `make help` command to list targets and help text
ubclaunchpad · Feb 12, 2019 · 673aada · 673aada
1 parent 3806f4b
commit 673aada
Show file tree

Hide file tree

Showing 5 changed files with 167 additions and 125 deletions.
diff --git a/.scripts/release.sh b/.scripts/release.sh
@@ -9,7 +9,7 @@ RELEASE=$(git describe --tags)
 echo "Building release $RELEASE"
 
 # Build, tag and push Inertia Docker image
-make daemon RELEASE="$RELEASE"
+make daemon-release RELEASE="$RELEASE"
 
 # Build Inertia Go binaries for specified platforms
 gox -output="inertia.$(git describe --tags).{{.OS}}.{{.Arch}}" \

diff --git a/.static/inertia.png b/.static/inertia.png
diff --git a/.travis.yml b/.travis.yml
@@ -25,7 +25,7 @@ jobs:
       install:
         - go get github.com/golang/dep/cmd/dep
         - dep ensure -v           # cache vendor
-        - make testdaemon-image   # cache images
+        - make daemon             # cache daemon image
         - make web-deps           # cache node_modules
 
     ############################
@@ -82,7 +82,7 @@ jobs:
       install: true
       script:
         - docker login -u $DOCKER_USER -p $DOCKER_KEY 
-        - make daemon RELEASE=latest
+        - make daemon-release RELEASE=latest
 
     ############################
     #  Build git tag (stable)  #

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -106,6 +106,11 @@ Note that if you install Inertia using these commands or any variation of `go in
 
 The Inertia codebase is split up into several components - this section gives a quick introduction on how to work with each.
 
+### Makefile
+
+The [Makefile](/Makefile) offers a lot of useful commands for development. Run
+`make help` to see the commands that are available.
+
 ### CLI
 
 Inertia's command line application is initiated in the root directory, but the majority of the code is in the `cmd` package. It is built on top of [cobra](https://github.com/spf13/cobra), a library for building command line applications.

diff --git a/Makefile b/Makefile
@@ -4,125 +4,186 @@ VPS_VERSION = latest
 VPS_OS = ubuntu
 RELEASE = test
 CLI_VERSION_VAR = main.Version
+PROJECTNAME=inertia
 
+.PHONY: help
+help: Makefile
+	@echo " Choose a command run in "$(PROJECTNAME)":\n"
+	@sed -n 's/^##//p' $< | column -t -s ':' |  sed -e 's/^/ /'
+
+## all: install production dependencies and build the Inertia CLI to project directory
 all: prod-deps cli
 
-# List all commands
-.PHONY: ls
-ls:
-	@$(MAKE) -pRrq -f $(lastword $(MAKEFILE_LIST)) : 2>/dev/null | awk -v RS= -F: '/^# File/,/^# Finished Make data base/ {if ($$1 !~ "^[#.]") {print $$1}}' | sort | egrep -v -e '^[^[:alnum:]]' -e '^$@$$' | xargs
+## deps: install all dependencies
+.PHONY: deps
+deps: prod-deps dev-deps docker-deps
 
+## lint: run static analysis for entire project
+.PHONY: lint
+lint: SHELL:=/bin/bash
+lint:
+	go vet ./...
+	go test -run xxxx ./...
+	diff -u <(echo -n) <(gofmt -d -s `find . -type f -name '*.go' -not -path "./vendor/*"`)
+	diff -u <(echo -n) <(golint `go list ./... | grep -v /vendor/`)
+	(cd ./daemon/web; npm run lint)
+	(cd ./daemon/web; npm run sass-lint)
+
+## clean: remove testenv, binaries, build directories, caches, and more
 .PHONY: clean
 clean: testenv-clean
 	go clean -testcache
 	rm -f ./inertia
 	rm -rf ./docs_build
 	find . -type f -name inertia.\* -exec rm {} \;
 
-# Install all dependencies
-.PHONY: deps
-deps: prod-deps dev-deps docker-deps
-
-# Sets up production dependencies
-.PHONY: prod-deps
-prod-deps:
-	dep ensure -v
-	make web-deps
-
-# Sets up test dependencies
-.PHONY: dev-deps
-dev-deps:
-	go get -u github.com/UnnoTed/fileb0x
-	go get -u golang.org/x/lint/golint
-
-.PHONY: docker-deps
-docker-deps:
-	bash test/docker_deps.sh
+##    ____________
+##  * CLI / DAEMON
+##    ‾‾‾‾‾‾‾‾‾‾‾‾
 
+## cli: build the inertia CLI binary into project directory
 .PHONY: cli
 cli:
 	go build -ldflags "-X $(CLI_VERSION_VAR)=$(RELEASE)"
 
-# Install Inertia with release version
+## install: install inertia CLI to $GOPATH
 .PHONY: install
 install:
 	go install -ldflags "-X $(CLI_VERSION_VAR)=$(RELEASE)"
 
-# Install Inertia with git tag as release version
-.PHONY: install-tagged
-install-tagged:
-	go install -ldflags "-X $(CLI_VERSION_VAR)=$(TAG)"
+## daemon: build the daemon image and save it to ./images
+.PHONY: daemon
+daemon:
+	mkdir -p ./images
+	rm -f ./images/inertia-daemon-image
+	docker build --build-arg INERTIA_VERSION=$(TAG) \
+		-t ubclaunchpad/inertia:test .
+	docker save -o ./images/inertia-daemon-image ubclaunchpad/inertia:test
+	docker rmi ubclaunchpad/inertia:test
 
-# Run static analysis
-.PHONY: lint
-lint: SHELL:=/bin/bash
-lint:
-	go vet ./...
-	go test -run xxxx ./...
-	diff -u <(echo -n) <(gofmt -d -s `find . -type f -name '*.go' -not -path "./vendor/*"`)
-	diff -u <(echo -n) <(golint `go list ./... | grep -v /vendor/`)
-	(cd ./daemon/web; npm run lint)
-	(cd ./daemon/web; npm run sass-lint)
+## gen: rewrite all generated code (mocks, scripts, etc.)
+.PHONY: gen
+gen: scripts mocks
+
+##    ___
+##  * WEB
+##    ‾‾‾
+
+## web-deps: install Inertia Web dependencies. use PACKAGE to install specific package
+.PHONY: web-deps
+web-deps:
+	(cd ./daemon/web; npm install $(PACKAGE))
+
+## web-run: run local development instance of Inertia Web
+.PHONY: web-run
+web-run:
+	(cd ./daemon/web; npm start)
+
+## web-sandbox: run sandboxed development instance of Inertia Web
+.PHONY: web-run
+web-run-sandbox:
+	(cd ./daemon/web; npm start:sandbox)
+
+## web-build: build Inertia Web
+.PHONY: web-build
+web-build:
+	(cd ./daemon/web; npm install --production; npm run build)
 
-# Run test suite without Docker ops
+##    _______
+##  * TESTING
+##    ‾‾‾‾‾‾‾
+
+## testenv: set up full test environment
+.PHONY: testenv
+testenv: docker-deps testenv-clean
+	# run nginx container for testing
+	docker run --name testcontainer -d nginx
+
+	# start vps container
+	docker build -f ./test/vps/$(VPS_OS).dockerfile \
+		-t $(VPS_OS)vps \
+		--build-arg VERSION=$(VPS_VERSION) \
+		./test
+	bash ./test/start_vps.sh $(SSH_PORT) $(VPS_OS)vps
+
+## testdaemon: create test daemon and scp the image to the test VPS for use as version "test"
+.PHONY: testdaemon
+testdaemon: daemon testdaemon-scp
+
+## test: run unit test suite
 .PHONY: test
 test:
 	go test ./... -short -ldflags "-X $(CLI_VERSION_VAR)=test" --cover
 
-# Run test suite without Docker ops
-.PHONY: test-v
-test-v:
-	go test ./... -short -ldflags "-X $(CLI_VERSION_VAR)=test" -v --cover
-
-# Run unit and integration tests - creates fresh test VPS and test daemon beforehand
-# Also attempts to run linter
+## test-all: build test daemon, set up testenv, and run unit and integration tests 
 .PHONY: test-all
 test-all:
 	make testenv VPS_OS=$(VPS_OS) VPS_VERSION=$(VPS_VERSION)
 	make testdaemon
 	go test ./... -ldflags "-X $(CLI_VERSION_VAR)=test" --cover
 
-# Run integration tests verbosely - creates fresh test VPS and test daemon beforehand
+## test-integration: build test daemon, set up testenv, and run integration tests only
 .PHONY: test-integration
 test-integration:
 	make testenv VPS_OS=$(VPS_OS) VPS_VERSION=$(VPS_VERSION)
 	make testdaemon
 	go test ./... -v -run 'Integration' -ldflags "-X $(CLI_VERSION_VAR)=test" --cover
 
-# Run integration tests verbosely without recreating test VPS
+## test-integration-fast: run integration tests only, but without setting up testenv
 .PHONY: test-integration-fast
 test-integration-fast:
 	make testdaemon
 	go test ./... -v -run 'Integration' -ldflags "-X $(CLI_VERSION_VAR)=test" --cover
 
-.PHONY: testenv-clean
-testenv-clean:
-	docker stop testvps testcontainer || true && docker rm testvps testcontainer || true
+##    _____________
+##  * DOCUMENTATION
+##    ‾‾‾‾‾‾‾‾‾‾‾‾‾
 
-# Create test VPS
-.PHONY: testenv
-testenv: docker-deps testenv-clean
-	# run nginx container for testing
-	docker run --name testcontainer -d nginx
+## docs: set up doc builder and build documentation site into ./docs from ./docs_src
+.PHONY: docs
+docs:
+	sh .scripts/build_docs.sh
 
-	# start vps container
-	docker build -f ./test/vps/$(VPS_OS).dockerfile \
-		-t $(VPS_OS)vps \
-		--build-arg VERSION=$(VPS_VERSION) \
-		./test
-	bash ./test/start_vps.sh $(SSH_PORT) $(VPS_OS)vps
+## run-docs: run local doc server from ./docs_src
+.PHONY: run-docs
+run-docs:
+	( cd docs_build/slate ; bundle exec middleman server --verbose )
 
-# Builds test daemon image and saves as inertia-daemon-image
-.PHONY: testdaemon-image
-testdaemon-image:
-	mkdir -p ./images
-	rm -f ./images/inertia-daemon-image
-	docker build --build-arg INERTIA_VERSION=$(TAG) \
-		-t ubclaunchpad/inertia:test .
-	docker save -o ./images/inertia-daemon-image ubclaunchpad/inertia:test
-	docker rmi ubclaunchpad/inertia:test
+##    _______
+##  * HELPERS
+##    ‾‾‾‾‾‾‾
 
-# Copies test daemon image to test VPS.
+## prod-deps: install only production dependencies
+.PHONY: prod-deps
+prod-deps:
+	dep ensure -v
+	make web-deps
+
+## dev-deps: install only development dependencies and tools
+.PHONY: dev-deps
+dev-deps:
+	go get -u github.com/UnnoTed/fileb0x
+	go get -u golang.org/x/lint/golint
+
+## docker-deps: download required docker containers
+.PHONY: docker-deps
+docker-deps:
+	bash test/docker_deps.sh
+
+## mocks: generate Go mocks
+.PHONY: mocks
+mocks:
+	counterfeiter -o ./daemon/inertiad/project/mocks/deployer.go \
+		./daemon/inertiad/project/deployment.go Deployer
+	counterfeiter -o ./daemon/inertiad/build/mocks/builder.go \
+		./daemon/inertiad/build/builder.go ContainerBuilder
+
+## scripts: recompile script assets
+.PHONY: scripts
+scripts:
+	fileb0x b0x.yml
+
+## testdaemon-scp: copy test daemon image from ./images to test VPS
 .PHONY: testdaemon-scp
 testdaemon-scp:
 	chmod 400 ./test/keys/id_rsa
@@ -133,61 +194,37 @@ testdaemon-scp:
 		./images/inertia-daemon-image \
 		root@0.0.0.0:/daemon-image
 
-# Create test daemon and scp the image to the test VPS for use.
-# Requires Inertia version to be "test"
-.PHONY: testdaemon
-testdaemon: testdaemon-image testdaemon-scp
+## testenv-clean: stop and shut down the test environment
+.PHONY: testenv-clean
+testenv-clean:
+	docker stop testvps testcontainer || true && docker rm testvps testcontainer || true
 
-# Run a test daemon locally
-.PHONY: localdaemon
-localdaemon:
-	bash ./test/start_local_daemon.sh
+##    _______________
+##  * RELEASE SCRIPTS
+##    ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
 
-# Creates a daemon release and pushes it to Docker Hub repository.
-# Requires access to the UBC Launch Pad Docker Hub.
-.PHONY: daemon
-daemon:
+## install-tagged: install Inertia with git tag as release version
+.PHONY: install-tagged
+install-tagged:
+	go install -ldflags "-X $(CLI_VERSION_VAR)=$(TAG)"
+
+## daemon-release: build the daemon and push it to the UBC Launch Pad Docker Hub
+.PHONY: daemon-release
+daemon-release:
 	docker build --build-arg INERTIA_VERSION=$(RELEASE) \
 		-t ubclaunchpad/inertia:$(RELEASE) .
 	docker push ubclaunchpad/inertia:$(RELEASE)
 
-# Recompiles assets. Use whenever a script in client/scripts is modified.
-.PHONY: scripts
-scripts:
-	fileb0x b0x.yml
-
-# Rewrites generated code
-.PHONY: gen
-gen: scripts
-	counterfeiter -o ./daemon/inertiad/project/mocks/deployer.go \
-		./daemon/inertiad/project/deployment.go Deployer
-	counterfeiter -o ./daemon/inertiad/build/mocks/builder.go \
-		./daemon/inertiad/build/builder.go ContainerBuilder
-
-# Install Inertia Web dependencies. Use PACKAGE to install something.
-.PHONY: web-deps
-web-deps:
-	(cd ./daemon/web; npm install $(PACKAGE))
-
-# Run local development instance of Inertia Web.
-.PHONY: web-run
-web-run:
-	(cd ./daemon/web; npm start)
-
-# Run sandboxed development instance of Inertia Web.
-.PHONY: web-run
-web-run-sandbox:
-	(cd ./daemon/web; npm start:sandbox)
-
-# Build and minify Inertia Web.
-.PHONY: web-build
-web-build:
-	(cd ./daemon/web; npm install --production; npm run build)
+## cli-release: cross-compile Inertia CLI binaries for distribution
+.PHONY: cli-release
+cli-release:
+	bash .scripts/release.sh
 
-.PHONY: docs
-docs:
-	sh .scripts/build_docs.sh
+##    ____________
+##  * EXPERIMENTAL
+##    ‾‾‾‾‾‾‾‾‾‾‾‾
 
-.PHONY: run-docs
-run-docs:
-	( cd docs_build/slate ; bundle exec middleman server --verbose )
+## localdaemon: run a test daemon locally, without testenv
+.PHONY: localdaemon
+localdaemon:
+	bash ./test/start_local_daemon.sh