Add section on conventions in Cluster API (#1213)

Getting started on the Cluster API projects, I found that the number
of acronyms can be confusing (e.g. CAPA: is it AWS or Azure?
CAPI: is it the API or the IBM Cloud provider?). This change aims to
help future newcomers to get familiar with the acronyms/abbreviations
used in the projects.

This change further makes small improvements to the tooling around
the GitBook: (1) ignore generated book files, and (2) add book build
and cleanup commands to the main Makefile.

Signed-off-by: erwinvaneyk <erwinvaneyk@gmail.com>

.gitignore

@@ -32,6 +32,7 @@ minikube.kubeconfig
 
 # GitBook - do not check in node_modules for a specific arch and os.
 docs/book/node_modules/
+docs/book/_book/
 
 # Common editor / temporary files
 *~

Makefile

@@ -205,6 +205,7 @@ docker-push-manifest: ## Push the fat manifest docker image. TODO: Update bazel
 clean: ## Remove all generated files
 	$(MAKE) clean-bazel
 	$(MAKE) clean-bin
+	$(MAKE) clean-book
 
 .PHONY: clean-bazel
 clean-bazel: ## Remove all generated bazel symlinks
@@ -224,9 +225,22 @@ verify:
 	./hack/verify-clientset.sh
 	./hack/verify-bazel.sh
 
+.PHONY: clean-book
+clean-book: ## Remove all generated GitBook files
+	rm -rf ./docs/book/_book
+
 ## --------------------------------------
 ## Others / Utilities
 ## --------------------------------------
 
-diagrams:
+.PHONY: diagrams
+diagrams: ## Build proposal diagrams
 	$(MAKE) -C docs/proposals/images
+
+.PHONY: book
+book: ## Build the GitBook
+	./hack/build-gitbook.sh
+
+.PHONY: serve-book
+serve-book: ## Build and serve the GitBook with live-reloading enabled
+	(cd ./docs/book && gitbook serve --live --open)

docs/book/ABBREVIATIONS.md

@@ -0,0 +1,9 @@
+# Acronyms and Abbreviations 
+
+Acronym or Abbreviation  | Full name
+-------------------------|---------------------
+CAPA                     | Cluster API Provider AWS
+CAPD                     | Cluster API Provider Docker
+CAPI                     | Cluster API
+CAPV                     | Cluster API Provider vSphere
+CAPZ                     | Cluster API Provider Azure

docs/book/RELEASE

@@ -26,7 +26,7 @@ This has only been verified to work on OSX. For platform agnostic testing see
 the [Testing with Netlify](#testing-with-netlify) section above.
 
 ```
-hack/build-gitbook.sh
+make book
 ```
 
 ## Verify the contents of the GitBook are correct by viewing the pages which 
@@ -36,9 +36,7 @@ should include new or changed content and:
 1) They are rendered as expected.
 
 ```
-cd docs/book
-gitbook serve
-# open localhost:4000 in a web browser
+make serve-book
 ```
 
 [markdown]: https://toolchain.gitbook.com/syntax/markdown.html

docs/book/SUMMARY.md

@@ -5,6 +5,7 @@
 ## Getting Started
 
 * [Glossary](GLOSSARY.md)
+* [Abbreviations](ABBREVIATIONS.md)
 * [Existing Providers](getting_started/existing_providers.md)
 
 ## Common Code

hack/build-gitbook.sh

@@ -19,9 +19,7 @@ set -o pipefail
 
 export KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
 
-cd $KUBE_ROOT
-
-pushd docs/book/
+pushd "${KUBE_ROOT}/docs/book/"
 npm install gitbook-cli -g
 npm install phantomjs-prebuilt
 npm ci