Add mdbook skeleton (#426)

common.mk

@@ -1,4 +1,5 @@
 
+include $(ROOT_DIR_RELATIVE)/versions.mk
 
 TOOLS_DIR := $(ROOT_DIR_RELATIVE)/hack/tools
 TOOLS_DIR_DEPS := $(TOOLS_DIR)/go.sum $(TOOLS_DIR)/go.mod $(TOOLS_DIR)/Makefile

docs/book/.gitignore

@@ -0,0 +1 @@
+book

docs/book/Makefile

@@ -0,0 +1,90 @@
+# Copyright 2021 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.
+
+ROOT_DIR_RELATIVE := ../..
+include $(ROOT_DIR_RELATIVE)/common.mk
+
+# Directories.
+MDBOOK := $(TOOLS_BIN_DIR)/mdbook
+MDBOOK_EMBED := $(TOOLS_BIN_DIR)/mdbook-embed
+MDBOOK_RELEASELINK := $(TOOLS_BIN_DIR)/mdbook-releaselink
+MDBOOK_TABULATE := $(TOOLS_BIN_DIR)/mdbook-tabulate
+GENCRDAPIREFERENCEDOCS := $(TOOLS_BIN_DIR)/gen-crd-api-reference-docs
+GENCRDAPIREFERENCEDOCS_SRCS := $(call rwildcard,.,gen-crd-api-reference-docs/*.*)
+CRD_DOCS := src/crd/cluster-api-aws.md src/crd/experimental.md src/crd/eks-control-plane.md
+BOOK_SRCS :=  $(filter-out $(CRD_DOCS), $(call rwildcard,.,*.*))
+
+API_DIRS := cmd/clusterawsadm/api/bootstrap/v1beta1 api/v1beta1 exp/api/v1beta1 controlplane/eks/api/v1beta1 bootstrap/eks/api/v1beta1 iam/api/v1beta1
+API_SRCS := $(foreach dir, $(API_DIRS), $(call rwildcard,../../$(dir),*.go))
+GENERATED_SRCS := $(foreach dir, $(API_DIRS),../../$(dir)/zz_generated.deepcopy.go ../../$(dir)/zz_generated.conversion.go ../../$(dir)/zz_generated.defaults.go)
+API_FILTERED_SRCS := $(filter-out $(GENERATED_SRCS), $(API_SRCS))
+
+OS := $(shell go env GOOS)
+ARCH := $(shell go env GOARCH)
+PATH := $(abspath $(TOOLS_BIN_DIR)):$(PATH)
+export PATH
+
+src/crd:
+	mkdir -p src/crd
+
+src/crd/index.md: $(API_FILTERED_SRCS) src/crd
+	$(MAKE) gen_crd_docs API_DIR="../.." OUT_FILE=$@
+
+.PHONY: gen_crd_docs
+gen_crd_docs: $(GENCRDAPIREFERENCEDOCS) src/crd $(GENCRDAPIREFERENCEDOCS_SRCS)
+	$(GENCRDAPIREFERENCEDOCS) -template-dir gen-crd-api-reference-docs/template -config "gen-crd-api-reference-docs/config.json" \
+		-api-dir $(API_DIR) \
+		-out-file $(OUT_FILE)
+
+src/clusterawsadm:
+	mkdir -p src/clusterawsadm
+
+terraform/out:
+	mkdir -p terraform/out
+
+terraform/out/amilist: terraform/out
+	CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o $@ ./cmd/amilist && chmod 755 $@
+
+.PHONY: generate
+generate: ## Generate any dependent files outside of a build
+	$(MAKE) -C ../ diagrams
+
+#src/SUMMARY_CLUSTERAWSADM.md: src/clusterawsadm $(CLUSTERAWSADMCMDREF_SRCS)
+#	go run ./cmd/clusterawsadmdocs > src/SUMMARY_CLUSTERAWSADM.md
+#
+## SUMMARY.md doesn't support processor statements, so construct it using cat
+#src/SUMMARY.md: src/SUMMARY_PREFIX.md src/SUMMARY_SUFFIX.md
+#	cat src/SUMMARY_PREFIX.md > src/SUMMARY.md
+#	cat src/SUMMARY_CLUSTERAWSADM.md >> src/SUMMARY.md
+#	cat src/SUMMARY_SUFFIX.md >> src/SUMMARY.md
+
+verify: generate ## Verify that dependent artifacts are up to date
+	@if !(git diff --quiet HEAD); then \
+		git diff; \
+		echo "generated files are out of date, run make generate"; exit 1; \
+	fi
+
+BOOK_DEPS := $(BOOK_SRCS) $(MDBOOK) $(MDBOOK_EMBED) $(MDBOOK_RELEASELINK) $(MDBOOK_TABULATE) #src/SUMMARY.md src/crd/index.md
+
+.PHONY: build
+build: $(BOOK_DEPS) ## Build the book
+	$(MDBOOK) build
+
+.PHONY: serve
+serve: $(BOOK_DEPS) ## Run a local webserver with the compiled book
+	$(MDBOOK) serve
+
+.PHONY: clean
+clean:
+	rm -rf book

docs/book/book.toml

@@ -0,0 +1,19 @@
+[book]
+authors = ["The Cluster API Provider IBMCloud Maintainers"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Kubernetes Cluster API Provider IBMCloud"
+
+[output.html]
+curly-quotes = true
+git-repository-url = "https://sigs.k8s.io/cluster-api-provider-ibmcloud"
+
+[preprocessor.tabulate]
+command = "mdbook-tabulate"
+
+[preprocessor.embed]
+command = "mdbook-embed"
+
+[preprocessor.releaselink]
+command = "mdbook-releaselink"

docs/book/src/SUMMARY.md

@@ -0,0 +1,16 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Getting Started](./getting-started.md)
+- [Topics](./topics/index.md)
+  - [VPC Cluster](./topics/vpc/index.md)
+    - [Prerequisites](./topics/vpc/prerequisites.md)
+    - [Creating a cluster](./topics/vpc/creating-a-cluster.md)
+  - [Power VS Cluster](./topics/powervs/index.md)
+    - [Prerequisites](./topics/powervs/prerequisites.md)
+    - [Creating a cluster](./topics/powervs/creating-a-cluster.md)
+- [Developer Guide](./developer/index.md)
+  - [Rapid iterative development with Tilt](./developer/tilt.md)
+  - [Release Process](./developer/release.md)
+- [Troubleshooting](./user/troubleshooting.md)
+- [Reference](./reference/reference.md)

docs/book/src/developer/index.md

@@ -0,0 +1 @@
+# Developer Guide

docs/book/src/developer/release.md

@@ -0,0 +1 @@
+# Release Process

docs/book/src/developer/tilt.md

@@ -0,0 +1 @@
+# Rapid iterative development with Tilt

docs/book/src/getting-started.md

@@ -0,0 +1 @@
+# Getting Started

docs/book/src/introduction.md

@@ -0,0 +1 @@
+# Introduction

docs/book/src/reference/reference.md

@@ -0,0 +1 @@
+# Reference

docs/book/src/topics/index.md

@@ -0,0 +1 @@
+# Topics

docs/book/src/topics/powervs/creating-a-cluster.md

@@ -0,0 +1 @@
+# Creating a cluster

docs/book/src/topics/powervs/index.md

@@ -0,0 +1 @@
+# Power VS Cluster

docs/book/src/topics/powervs/prerequisites.md

@@ -0,0 +1 @@
+# Prerequisites

docs/book/src/topics/vpc/creating-a-cluster.md

@@ -0,0 +1 @@
+# Creating a cluster

docs/book/src/topics/vpc/index.md

@@ -0,0 +1 @@
+# VPC Cluster

docs/book/src/topics/vpc/prerequisites.md

@@ -0,0 +1 @@
+# Prerequisites

docs/book/src/user/troubleshooting.md

@@ -0,0 +1 @@
+# Troubleshooting

hack/tools/.gitignore

@@ -0,0 +1,2 @@
+bin
+share

hack/tools/Makefile

@@ -12,12 +12,35 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+ROOT_DIR_RELATIVE := ../..
+include $(ROOT_DIR_RELATIVE)/common.mk
+
 # Directories.
 BIN_DIR := bin
+SHARE_DIR := share
+
+OS := $(shell go env GOOS)
+RUST_TARGET := unknown-$(OS)-gnu
+
+ifeq ($(OS), darwin)
+	RUST_TARGET := apple-darwin
+endif
 
 $(BIN_DIR):
 	mkdir -p $@
 
+$(SHARE_DIR):
+	mkdir -p $@
+
+MDBOOK_EXTRACT_COMMAND := tar xfvz $(SHARE_DIR)/mdbook.tar.gz -C bin
+MDBOOK_ARCHIVE_EXT := .tar.gz
+
+ifeq ($(OS), windows)
+	RUST_TARGET := pc-windows-msvc
+	MDBOOK_ARCHIVE_EXT := .zip
+	MDBOOK_EXTRACT_COMMAND := unzip -d /tmp
+endif
+
 GOLANGCI_LINT := $(BIN_DIR)/golangci-lint
 $(GOLANGCI_LINT): $(BIN_DIR) go.mod go.sum # Build golangci-lint from tools folder.
 	go build -tags=tools -o $@ github.com/golangci/golangci-lint/cmd/golangci-lint
@@ -26,6 +49,28 @@ KUSTOMIZE := $(BIN_DIR)/kustomize
 $(KUSTOMIZE): $(BIN_DIR) go.mod go.sum # Build kustomize from tools folder.
 	CGO_ENABLED=0 go build -tags=tools -o $@ sigs.k8s.io/kustomize/kustomize/v3
 
+MDBOOK_SHARE := $(SHARE_DIR)/mdbook$(MDBOOK_ARCHIVE_EXT)
+$(MDBOOK_SHARE): ../../versions.mk $(SHARE_DIR)
+	curl -sL -o $(MDBOOK_SHARE) "https://github.com/rust-lang/mdBook/releases/download/$(MDBOOK_VERSION)/mdBook-$(MDBOOK_VERSION)-x86_64-$(RUST_TARGET)$(MDBOOK_ARCHIVE_EXT)"
+
+MDBOOK := $(BIN_DIR)/mdbook
+$(MDBOOK): $(BIN_DIR) $(MDBOOK_SHARE)
+	$(MDBOOK_EXTRACT_COMMAND)
+	chmod +x $@
+	touch -m $@
+
+MDBOOK_EMBED := $(BIN_DIR)/mdbook-embed
+$(MDBOOK_EMBED): $(BIN_DIR) go.mod go.sum
+	go build -tags=tools -o $(BIN_DIR)/mdbook-embed sigs.k8s.io/cluster-api/hack/tools/mdbook/embed
+
+MDBOOK_RELEASELINK := $(BIN_DIR)/mdbook-releaselink
+$(MDBOOK_RELEASELINK): $(BIN_DIR) go.mod go.sum
+	go build -tags=tools -o $(BIN_DIR)/mdbook-releaselink sigs.k8s.io/cluster-api/hack/tools/mdbook/releaselink
+
+MDBOOK_TABULATE := $(BIN_DIR)/mdbook-tabulate
+$(MDBOOK_TABULATE): $(BIN_DIR) go.mod go.sum
+	go build -tags=tools -o $(BIN_DIR)/mdbook-tabulate sigs.k8s.io/cluster-api/hack/tools/mdbook/tabulate
+
 GOJQ := $(BIN_DIR)/gojq
 $(GOJQ): $(BIN_DIR) go.mod go.sum
 	go build -tags=tools -o $@ github.com/itchyny/gojq/cmd/gojq

hack/tools/go.mod

@@ -4,21 +4,20 @@ go 1.16
 
 require (
 	github.com/blang/semver v3.5.1+incompatible
-	github.com/drone/envsubst/v2 v2.0.0-20210615175204-7bf45dbf5372
+	github.com/drone/envsubst/v2 v2.0.0-20210730161058-179042472c46
 	github.com/golangci/golangci-lint v1.41.1
 	github.com/hashicorp/go-multierror v1.1.1
 	github.com/itchyny/gojq v0.12.5
 	github.com/joelanford/go-apidiff v0.1.0
-	github.com/onsi/ginkgo v1.16.4
+	github.com/onsi/ginkgo v1.16.5
 	github.com/pkg/errors v0.9.1
-	github.com/sergi/go-diff v1.2.0 // indirect
-	golang.org/x/exp v0.0.0-20210625193404-fa9d1d177d71 // indirect
-	golang.org/x/tools v0.1.5
+	golang.org/x/tools v0.1.8-0.20211029000441-d6a9af8af023
 	gotest.tools/gotestsum v1.6.4
-	k8s.io/code-generator v0.22.2
-	k8s.io/klog/v2 v2.9.0
-	sigs.k8s.io/controller-runtime/tools/setup-envtest v0.0.0-20210827150604-1730628f118b
-	sigs.k8s.io/controller-tools v0.7.0
-	sigs.k8s.io/kubebuilder/docs/book/utils v0.0.0-20210702145813-742983631190
+	k8s.io/code-generator v0.23.0-alpha.4
+	k8s.io/klog/v2 v2.30.0
+	sigs.k8s.io/cluster-api/hack/tools v0.0.0-20211118171502-aafa086da595
+	sigs.k8s.io/controller-runtime/tools/setup-envtest v0.0.0-20211110210527-619e6b92dab9
+	sigs.k8s.io/controller-tools v0.7.1-0.20211110210727-ab52f76cc7d1
+	sigs.k8s.io/kubebuilder/docs/book/utils v0.0.0-20211028165026-57688c578b5d
 	sigs.k8s.io/kustomize/kustomize/v3 v3.10.0
 )