docs: started to add docs site (fidelity#102)

* docs: started to add docs site

* docs: add GH action to publish docs

.github/workflows/release-docs.yml

@@ -0,0 +1,24 @@
+name: goreleaser
+
+on:
+    push:
+        tags:
+            - "*"
+
+jobs:
+    goreleaser:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v2
+              with:
+                  fetch-depth: 0
+                  submodules: true
+            - name: Build Docs
+              run: |
+                make docs-build
+            - name: Deploy
+              uses: peaceiris/actions-gh-pages@v3
+              with:
+                github_token: ${{ secrets.GITHUB_TOKEN }}
+                publish_dir: ./docs/book/book

.gitignore

@@ -10,9 +10,13 @@ coverage.out
 # GoReleaser dist folder
 dist/
 
-# Tools bin folder
+# Bin
 bin/
 
+# Tools
+hack/tools/bin
+hack/tools/share
+
 # direnv files:
 .envrc
 

Makefile

@@ -1,21 +1,54 @@
+# Build information
 build_date := $(shell date +%Y-%m-%dT%H:%M:%SZ)
 git_commit := $(shell git rev-parse --short HEAD)
-
 version_pkg := github.com/fidelity/kconnect/internal/version
+OS := $(shell go env GOOS)
+ARCH := $(shell go env GOARCH)
+UNAME := $(shell uname -s)
 
 # Directories
 gopath := $(shell go env GOPATH)
 GOBIN ?= $(gopath)/bin
 TOOLS_DIR := hack/tools
 TOOLS_BIN_DIR := $(TOOLS_DIR)/bin
+TOOLS_SHARE_DIR := $(TOOLS_DIR)/share
 BIN_DIR := bin
+SHARE_DIR := share
+PATH := $(abspath $(TOOLS_BIN_DIR)):$(PATH)
+export PATH
+
+$(TOOLS_BIN_DIR):
+	mkdir -p $@
+
+$(TOOLS_SHARE_DIR):
+	mkdir -p $@
+
+# Docs
+MDBOOK_VERSION := v0.4.3
+BOOKS_DIR := docs/book
+RUST_TARGET := unknown-$(OS)-gnu
+MDBOOK_EXTRACT_COMMAND := tar xfvz $(TOOLS_SHARE_DIR)/mdbook.tar.gz -C $(TOOLS_BIN_DIR)
+MDBOOK_ARCHIVE_EXT := .tar.gz
+ifeq ($(OS), windows)
+	RUST_TARGET := pc-windows-msvc
+	MDBOOK_ARCHIVE_EXT := .zip
+	MDBOOK_EXTRACT_COMMAND := unzip -d /tmp
+endif
+
+ifeq ($(OS), darwin)
+	RUST_TARGET := apple-darwin
+endif
 
 # Binaries
 GOLANGCI_LINT := $(TOOLS_BIN_DIR)/golangci-lint
 CONTROLLER_GEN := $(TOOLS_BIN_DIR)/controller-gen
 DEFAULTER_GEN := $(TOOLS_BIN_DIR)/defaulter-gen
 CONVERSION_GEN := $(TOOLS_BIN_DIR)/conversion-gen
 MOCKGEN := $(TOOLS_BIN_DIR)/mockgen
+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
 
 .DEFAULT_GOAL := help
 
@@ -78,6 +111,31 @@ $(CONVERSION_GEN): $(TOOLS_DIR)/go.mod # Get and build conversion-gen
 $(MOCKGEN): $(TOOLS_DIR)/go.mod # Get and build mockgen
 	cd $(TOOLS_DIR); go build -tags=tools -o $(subst hack/tools/,,$@) github.com/golang/mock/mockgen
 
+##@ Docs
+
+MDBOOK_SHARE := $(TOOLS_SHARE_DIR)/mdbook$(MDBOOK_ARCHIVE_EXT)
+$(MDBOOK_SHARE): $(TOOLS_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 := $(TOOLS_BIN_DIR)/mdbook
+$(MDBOOK): $(TOOLS_BIN_DIR) $(MDBOOK_SHARE)
+	$(MDBOOK_EXTRACT_COMMAND)
+	chmod +x $@
+	touch -m $@
+
+
+.PHONY: docs-build
+docs-build: $(MDBOOK) ## Build the kconnect book
+	$(MDBOOK) build $(BOOKS_DIR)
+
+.PHONY: docs-serve
+docs-serve: $(MDBOOK) ## Run a local webserver with the compiled book
+	$(MDBOOK) serve $(BOOKS_DIR)
+
+.PHONY: docs-clean
+docs-clean:
+	rm -rf $(BOOKS_DIR)/book
+
 
 .PHONY: help
 help:  ## Display this help. Thanks to https://suva.sh/posts/well-documented-makefiles/

README.md

@@ -10,6 +10,15 @@ kconnect is a CLI utility that can be used to discover and securely access Kuber
 
 Based on the authentication mechanism chosen the CLI will discover Kubernetes clusters you are allowed to access in a target hosting environment (i.e. EKS, AKS, Rancher) and generate a kubeconfig for a chosen cluster.
 
+## Features
+
+- Authenticate using SAML against a number of IdP
+- Discover EKS clusters
+- Generate a kubeconfig for a cluster
+- Query history of connected servers
+- Regenerate the kubeconfig from your history by using an id or an alias
+- Import defaults values for your company
+
 ## Installation
 
 [Releases](https://github.com/fidelity/kconnect/releases) are available for download for OSX, Linux and Windows.
@@ -40,4 +49,4 @@ Documentation is contained in the `/docs` directory. The [index is here](docs/RE
 
 ## Contributions
 
-Contributions are very welcome. Please read the [contributing guide](CONTRIBUTING.md).
+Contributions are very welcome. Please read the [contributing guide](CONTRIBUTING.md) or see the docs.

docs/book/.gitignore

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

docs/book/book.toml

@@ -0,0 +1,11 @@
+[book]
+authors = ["The kconnect Maintainers"]
+language = "en"
+multilingual = false
+src = "src"
+title = "kconnect - The Kubernetes Connection Manager CLI"
+
+[output.html]
+curly-quotes = true
+git-repository-url = "https://github.com/fidelity/kconnect"
+

docs/book/src/SUMMARY.md

@@ -0,0 +1,8 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Installation](./installation.md)
+- [Getting Started](./getting-started.md)
+- [Commands](./commands/index.md)
+  - [use](./commands/use.md)
+- [Contributing](./contributing.md)

docs/book/src/commands/index.md

@@ -0,0 +1 @@
+# Commands

docs/book/src/commands/use.md

@@ -0,0 +1,8 @@
+# kconnect use
+
+## Purpose
+
+The purpose of the **use** command is to discover clusters you have access to in a cluster provider (i.e. EKS, AKS) using your identity which is supplied by a specific IdP.
+
+It will query the cluster provider and get a list of clusters you have access to. When you select a cluster to connect to your kubeconfig will be updated with the connection details for the selected cluster.
+

docs/book/src/contributing.md

@@ -0,0 +1 @@
+{{#include ../../../CONTRIBUTING.md:2:}}

docs/book/src/getting-started.md

@@ -0,0 +1,15 @@
+# Getting started
+
+Once you have installed kconnect you can see a list of the commands available by running:
+
+```bash
+kconnect
+```
+
+If you wanted to discover clusters in EKS and generate a kubeconfig for a selected cluster you can run the following command which will guide you through connecting:
+
+```bash
+kconnect use eks --idp-protocol saml
+```
+
+NOTE: only saml is supported at present for IdP.

docs/book/src/installation.md

@@ -0,0 +1,9 @@
+# Installation
+
+[Releases](https://github.com/fidelity/kconnect/releases) are available for download for OSX, Linux and Windows.
+
+To install on OSX you can use homebrew:
+
+```bash
+brew install fidelity/tap/kconnect
+```

docs/book/src/introduction.md

@@ -0,0 +1 @@
+{{#include ../../../README.md:2:}}