📖 Quickstart / add other sections

Signed-off-by: Vince Prignano <vincepri@vmware.com>
kubernetes-sigs · Sep 6, 2019 · 44eb8c3 · 44eb8c3
1 parent a3417af
commit 44eb8c3
Show file tree

Hide file tree

Showing 28 changed files with 560 additions and 36 deletions.
diff --git a/Makefile b/Makefile
@@ -280,4 +280,4 @@ diagrams: ## Build proposal diagrams
 
 .PHONY: serve-book
 serve-book: ## Build and serve the book with live-reloading enabled
-	(cd ./docs/book && mdbook serve)
+	$(MAKE) -C docs/book serve
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@
 - [Scope, objectives, goals and requirements](./docs/scope-and-objectives.md)
 - [Feature proposals](./docs/proposals)
 - [Reference use cases](./docs/staging-use-cases.md)
-- [Quick Start](https://cluster-api.sigs.k8s.io/quick-start.html)
+- [Quick Start](https://cluster-api.sigs.k8s.io/user/quick-start.html)
 
 ## What is the Cluster API?
 

diff --git a/docs/Makefile b/docs/Makefile
@@ -17,6 +17,7 @@ ROOT_DIR:=$(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
 SOURCES := $(shell find ${ROOT_DIR} -name \*.plantuml)
 DIAGRAMS := $(SOURCES:%.plantuml=%.png)
 
+.PHONY: diagrams
 diagrams: $(DIAGRAMS)
 
 %.png: %.plantuml
@@ -26,5 +27,3 @@ diagrams: $(DIAGRAMS)
 		--user $(shell id -u):$(shell id -g) \
 		us.gcr.io/k8s-artifacts-prod/cluster-api/plantuml:1.2019.6 \
 		-v /workdir/$(shell echo '$^' | sed -e 's,.*docs/,,g' )
-
-.PHONY: diagrams
diff --git a/docs/book/Makefile b/docs/book/Makefile
@@ -0,0 +1,29 @@
+# Copyright 2019 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Directories.
+ROOT_DIR:=$(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
+TOOLS_DIR := ../../hack/tools
+TOOLS_BIN_DIR := $(TOOLS_DIR)/bin
+BIN_DIR := bin
+
+# Binaries.
+TABULATE := $(TOOLS_BIN_DIR)/tabulate
+
+$(TABULATE): $(TOOLS_DIR)/go.mod
+	cd $(TOOLS_DIR); go build -tags=tools -o $(BIN_DIR)/tabulate ./tabulate
+
+.PHONY: serve
+serve:
+	mdbook serve
diff --git a/docs/book/book.toml b/docs/book/book.toml
@@ -8,3 +8,6 @@ title = "The Cluster API Book"
 [output.html]
 curly-quotes = true
 git-repository-url = "https://sigs.k8s.io/cluster-api"
+
+[preprocessor.foo]
+command = "./tabulate.sh"
diff --git a/docs/book/install-and-build.sh b/docs/book/install-and-build.sh
@@ -60,4 +60,5 @@ curl -sL -o /tmp/mdbook.${ext} "https://github.com/rust-lang-nursery/mdBook/rele
 ${cmd} /tmp/mdbook.${ext}
 chmod +x /tmp/mdbook
 
-/tmp/mdbook build docs/book
+# Finally build the book.
+(cd docs/book && /tmp/mdbook build)
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
@@ -2,19 +2,21 @@
 
 [Introduction](./introduction.md)
 
-[Quick Start](./quick-start.md)
+- [User Guide](./user/guide.md)
+    - [Concepts](./user/concepts.md)
+    - [Quick Start](./user/quick-start.md)
 
-- [Architecture](./architecture/architecture.md)
+- [Developer Guide](./architecture/developer-guide.md)
     - [Repository Layout](./architecture/repository-layout.md)
     - [Controllers](./architecture/controllers.md)
         - [Cluster](./architecture/controllers/cluster.md)
         - [Machine](./architecture/controllers/machine.md)
         - [MachineSet](./architecture/controllers/machine-set.md)
         - [MachineDeployment](./architecture/controllers/machine-deployment.md)
-
-- [Clusterctl](./clusterctl/clusterctl.md)
-
-- [Provider Implementers](./providers/implementers.md)
+    - [Provider Implementers](./providers/implementers.md)
+        - [v1alpha1 to v1alpha2](./providers/v1alpha1-to-v1alpha2.md)
+    - [Tooling](./tooling/tooling.md)
+        - [Clusterctl](./tooling/clusterctl.md)
 
 - [Reference](./reference/reference.md)
     - [Abbreviations](./reference/abbreviations.md)

diff --git a/docs/book/src/architecture/architecture.md b/docs/book/src/architecture/architecture.md
diff --git a/docs/book/src/architecture/developer-guide.md b/docs/book/src/architecture/developer-guide.md
@@ -0,0 +1 @@
+# Developer Guide
diff --git a/docs/book/src/glossary.md b/docs/book/src/glossary.md
diff --git a/docs/book/src/images/management-cluster.svg b/docs/book/src/images/management-cluster.svg
diff --git a/docs/book/src/introduction.md b/docs/book/src/introduction.md
@@ -1,7 +1,7 @@
 # The Cluster API Book <div style="float: right; position: relative; display: inline;"><img src="images/introduction.png" width="160px" /></div>
 
 **Note:** Impatient readers may head straight to [Quick
-Start](quick-start.md).
+Start](./user/quick-start.md).
 
 **Using Cluster API v1alpha1? Check the [legacy
 documentation](https://release-0-1.cluster-api.sigs.k8s.io)**
@@ -14,4 +14,4 @@ manage the lifecycle of a Kubernetes cluster.
 
 {{#include ../../scope-and-objectives.md:Goals}}
 
-{{#include ../../../README.md:Get Involved}}
+{{#include ../../../README.md:Community}}
diff --git a/...eveloper/v1alpha1-compared-to-v1alpha2.md → ...ook/src/providers/v1alpha1-to-v1alpha2.md b/...eveloper/v1alpha1-compared-to-v1alpha2.md → ...ook/src/providers/v1alpha1-to-v1alpha2.md
@@ -25,7 +25,6 @@ controllers that are responsible for the core types:
 * Machine
 * MachineSet
 * MachineDeployment
-* [plus a few more](../../pkg/apis/cluster/v1alpha2)
 
 Bootstrap providers are an entirely new concept aimed at reducing the amount of kubeadm boilerplate that every provider
 reimplemented in v1alpha1. The Bootstrap provider is responsible for running a controller that generates data necessary
@@ -41,7 +40,7 @@ bootstrap data to turn the infrastructure into a Kubernetes cluster.
 
 Actuators are interfaces that the Cluster API controller calls. A provider pulls in the generic Cluster API controller
 and then registers actuators to run specific infrastructure logic (calls to the provider cloud).
- 
+
 ### v1alpha2
 
 Actuators are not used in this version. Cluster API's controllers are no longer shared across providers and therefore
@@ -57,11 +56,11 @@ create a cloud instance for Kubernetes to run on.
 
 `clusterctl` was a command line tool packaged with v1alpha1 providers. The goal of this tool was to go from nothing to a
 running management cluster in whatever environment the provider was built for. For example, Cluster-API-Provider-AWS
-packaged a `clusterctl` that created a Kubernetes cluster in EC2 and installed the necessary controllers to respond to 
+packaged a `clusterctl` that created a Kubernetes cluster in EC2 and installed the necessary controllers to respond to
 Cluster API's APIs.
 
 ### v1alpha2
 
-`clusterctl` is likely becoming provider-agnostic meaning one clusterctl is bundled with Cluster API and can be reused 
+`clusterctl` is likely becoming provider-agnostic meaning one clusterctl is bundled with Cluster API and can be reused
 across providers. Work here is still being figured out but providers will not be packaging their own `clusterctl`
 anymore.
diff --git a/docs/book/src/quick-start.md b/docs/book/src/quick-start.md
diff --git a/docs/book/src/reference/glossary.md b/docs/book/src/reference/glossary.md
@@ -137,7 +137,12 @@ The pivot process is also used for deleting a management cluster and could also
 
 See [Infrastructure Provider](#user-content-infrastructure-provider)
 
-##### Provider implementation
+### Provider components
+
+Refers to the YAML artifact a provider publishes as part of their releases which is required to use the provider components,
+it usually contains Custom Resource Definitions (CRDs), Deployments (to run the controller manager), RBAC, etc.
+
+### Provider implementation
 
 Existing Cluster API implementations consist of generic and infrastructure provider-specific logic. The [infrastructure provider](#infrastructure-provider)-specific logic is currently maintained in infrastructure provider repositories.
 

diff --git a/docs/book/src/reference/providers.md b/docs/book/src/reference/providers.md
@@ -27,6 +27,6 @@ support v1alpha2 API types.
 
 Following are the implementations managed by third-parties adopting the standard cluster-api and/or machine-api being developed here.
 
-  * Kubermatic machine-controller, https://github.com/kubermatic/machine-controller/tree/master
-  * Machine API Operator, https://github.com/openshift/machine-api-operator/tree/master
-  * Machine-controller-manager, https://github.com/gardener/machine-controller-manager/tree/cluster-api
+  * [Kubermatic machine controller](https://github.com/kubermatic/machine-controller/tree/master)
+  * [Machine API Operator](https://github.com/openshift/machine-api-operator/tree/master)
+  * [Machine controller manager](https://github.com/gardener/machine-controller-manager/tree/cluster-api)
diff --git a/docs/book/src/clusterctl/clusterctl.md → docs/book/src/tooling/clusterctl.md b/docs/book/src/clusterctl/clusterctl.md → docs/book/src/tooling/clusterctl.md
diff --git a/docs/book/src/tooling/tooling.md b/docs/book/src/tooling/tooling.md
@@ -0,0 +1 @@
+# Tooling
diff --git a/docs/book/src/user/concepts.md b/docs/book/src/user/concepts.md
@@ -0,0 +1 @@
+# Concepts
diff --git a/docs/book/src/user/guide.md b/docs/book/src/user/guide.md
@@ -0,0 +1 @@
+# User Guide