scripts, docs: update api document (#1346)

Makefile

@@ -7,10 +7,10 @@ BASIC_TEST_PKGS := $(filter-out github.com/pingcap/pd/pkg/integration_test,$(TES
 PACKAGES := go list ./...
 PACKAGE_DIRECTORIES := $(PACKAGES) | sed 's|github.com/pingcap/pd/||'
 GOCHECKER := awk '{ print } END { if (NR > 0) { exit 1 } }'
-RETOOL:= ./hack/retool
+RETOOL:= ./scripts/retool
 
-GOFAIL_ENABLE  := $$(find $$PWD/ -type d | grep -vE "(\.git|\.retools)" | xargs ./hack/retool do gofail enable)
-GOFAIL_DISABLE := $$(find $$PWD/ -type d | grep -vE "(\.git|\.retools)" | xargs ./hack/retool do gofail disable)
+GOFAIL_ENABLE  := $$(find $$PWD/ -type d | grep -vE "(\.git|\.retools)" | xargs ./scripts/retool do gofail enable)
+GOFAIL_DISABLE := $$(find $$PWD/ -type d | grep -vE "(\.git|\.retools)" | xargs ./scripts/retool do gofail disable)
 
 LDFLAGS += -X "$(PD_PKG)/server.PDReleaseVersion=$(shell git describe --tags --dirty)"
 LDFLAGS += -X "$(PD_PKG)/server.PDBuildTS=$(shell date -u '+%Y-%m-%d %I:%M:%S')"
@@ -61,35 +61,35 @@ basic-test:
 
 # These need to be fixed before they can be ran regularly
 check-fail:
-	CGO_ENABLED=0 ./hack/retool do gometalinter.v2 --disable-all \
+	CGO_ENABLED=0 ./scripts/retool do gometalinter.v2 --disable-all \
 	  --enable errcheck \
 	  $$($(PACKAGE_DIRECTORIES))
-	CGO_ENABLED=0 ./hack/retool do gosec $$($(PACKAGE_DIRECTORIES))
+	CGO_ENABLED=0 ./scripts/retool do gosec $$($(PACKAGE_DIRECTORIES))
 
 check-all: static lint
 	@echo "checking"
 
 retool-setup: export GO111MODULE=off
 retool-setup: 
 	@which retool >/dev/null 2>&1 || go get github.com/twitchtv/retool
-	@./hack/retool sync
+	@./scripts/retool sync
 
 check: retool-setup check-all
 
 static:
 	@ # Not running vet and fmt through metalinter becauase it ends up looking at vendor
 	gofmt -s -l $$($(PACKAGE_DIRECTORIES)) 2>&1 | $(GOCHECKER)
-	./hack/retool do govet --shadow $$($(PACKAGE_DIRECTORIES)) 2>&1 | $(GOCHECKER)
+	./scripts/retool do govet --shadow $$($(PACKAGE_DIRECTORIES)) 2>&1 | $(GOCHECKER)
 
-	CGO_ENABLED=0 ./hack/retool do gometalinter.v2 --disable-all --deadline 120s \
+	CGO_ENABLED=0 ./scripts/retool do gometalinter.v2 --disable-all --deadline 120s \
 	  --enable misspell \
 	  --enable megacheck \
 	  --enable ineffassign \
 	  $$($(PACKAGE_DIRECTORIES))
 
 lint:
 	@echo "linting"
-	CGO_ENABLED=0 ./hack/retool do revive -formatter friendly -config revive.toml $$($(PACKAGES))
+	CGO_ENABLED=0 ./scripts/retool do revive -formatter friendly -config revive.toml $$($(PACKAGES))
 
 travis_coverage:
 ifeq ("$(TRAVIS_COVERAGE)", "1")

docs/development.md

@@ -16,7 +16,7 @@ Official lints are ran with:
     make check
 
 This will use `go get` to install `retool` which then vendors the linter tools local to the project.
-Linter versions are changed with [hack/retool-install.sh](../hack/retool-install.sh).
+Linter versions are changed with [scripts/retool-install.sh](../scripts/retool-install.sh).
 
 ## Testing
 
@@ -34,11 +34,7 @@ This takes a while to run. The test suite uses a fork of [gocheck](http://labix.
 
 We use [RAML 1.0](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md) to manage the API documentation, and the raml file is placed in `server/api/api.raml`. We also use [raml2html](https://github.com/raml2html/raml2html) to generate a more readable html file, which is placed in `docs/api.html`. When a PR involves API changes, you need to update the raml file within the same PR.
 
-Consider that raml2html depends on various npm packages and can only be run under a specific version of node. It is recommended to use docker to simplify the compilation of raml. You can run it in the root directory of PD:
-
-    docker pull mattjtodd/raml2html:latest
-    docker run --rm -v $PWD:/raml mattjtodd/raml2html -i /raml/server/api/api.raml -o /raml/docs/api.html
-
+Consider that raml2html depends on various npm packages and can only be run under a specific version of node. It is recommended to use docker to simplify the compilation of raml. You can update html file with [scripts/build-api.sh](../scripts/build-api.sh)
 
 ## Error responses
 

scripts/build-api.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Make sure docker is installed before executing it.
+
+docker pull mattjtodd/raml2html:latest
+docker run --rm -v $PWD:/raml mattjtodd/raml2html -i /raml/server/api/api.raml -o /raml/docs/api.html
+

scripts/retool-install.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# This script generates tools.json
+# It helps record what releases/branches are being used
+
+cd $(dirname "$0")/..
+which retool >/dev/null || go get github.com/twitchtv/retool
+
+# tool environment
+# check runner
+./scripts/retool add gopkg.in/alecthomas/gometalinter.v2 v2.0.5
+# check spelling
+./scripts/retool add github.com/client9/misspell/cmd/misspell v0.3.4
+# checks correctness
+./scripts/retool add github.com/gordonklaus/ineffassign 7bae11eba15a3285c75e388f77eb6357a2d73ee2
+./scripts/retool add honnef.co/go/tools/cmd/megacheck master
+./scripts/retool add github.com/dnephin/govet 4a96d43e39d340b63daa8bc5576985aa599885f6
+# slow checks
+./scripts/retool add github.com/kisielk/errcheck v1.1.0
+# linter
+./scripts/retool add github.com/mgechev/revive 7773f47324c2bf1c8f7a5500aff2b6c01d3ed73b
+./scripts/retool add github.com/securego/gosec/cmd/gosec 1.0.0
+# go fail
+./scripts/retool add github.com/pingcap/gofail master