Update Gitbook release process (#659)

* Remove mermaid module because it is currently unused and does not
always install cleanly.

* Introduce npm-shrinkwrap so that npm installations are reproducable.

* Update gitbook release documentation.

* Clarify verification instructions.

* Update GitBook.

* Remove rendered Gitbook from repo in preparation for using firebase
instead.

* Install gitbook cli.

* Update documentation for netlify.

* Add Netlify configuration toml.

* Update link to homepage so that it points to the book and not
the GitHub repository.

* Remove base from netlify.toml. The build script already accounts
for the correct location...

* Remove reference to no longer existent KEP. :(

* Disable redirects until the cluster-api.sigs.k8s.io domain has
been created.

* Reenable netlify redirects now that the cluster-api.sigs.k8s.io
domain exists.

docs/book/RELEASE

@@ -1,11 +1,37 @@
-To push the docs you must be an admin until we have proper CI around this.
-
+# Overview
+
+The Cluster API documentation is currently written in [Markdown][markdown]
+and rendered into static HTML/CSS/JavaScript using [GitBook][gitbook] and various
+[plugins][plugins]. It is automatically built using a [script](../../hack/build-gitbook.sh)
+and continuously deployed using a shared Netlify account.
+
+# Making changes
+
+The GitBook source is located in [./docs/book](../../docs/book) and the static
+content is generated into [./docs/book/_book](../../docs/book/_book) but not
+checked into version control. Netlify will automatically rebuild the 
+documentation on each merge to master.
+
+## Testing locally
+
 ```
-cd docs/book/
-gitbook install
-gitbook build
-cd ../../
-git add docs/book/_book
-git commit
-git subtree push --prefix docs/book/_book origin gh-pages
+hack/build-gitbook.sh
 ```
+
+## Verify the contents of the GitBook are correct by viewing the pages which 
+should include new or changed content and:
+
+0) Ensuring the expected changes are there.
+1) They are rendered as expected.
+
+```
+cd docs/book
+gitbook serve
+# open localhost:4000 in a web browser
+```
+
+## Finally submit a PR
+
+[markdown]: https://toolchain.gitbook.com/syntax/markdown.html
+[gitbook]: https://toolchain.gitbook.com/
+[plugins]: https://toolchain.gitbook.com/plugins/

docs/book/SUMMARY.md

@@ -26,7 +26,3 @@
 * [Register Controllers](provider_implementations/register_controllers.md)
 * [Building, Running, and Testing](provider_implementations/building_running_and_testing.md)
 
-## Appendices
-
-* [Cluster API KEP](appendices/keps/0003-cluster-api.md)
-

docs/book/book.json

@@ -1,6 +1,6 @@
 {
   "plugins": ["theme-api", "panel", "sequence-diagrams", "ga", "codegroup",
-              "mermaid", "include-codeblock"],
+              "include-codeblock"],
   "pluginsConfig": {
     "theme-api": {
       "split": true