[docs] - Add MdBook for documentation and GHA workflow (#115)

* start creating user docs with mdbook
* don't run code actions for docs changes
* update gitignore for devbox, add note devbox install takes a while

.github/workflows/build_test_ci.yml

@@ -2,9 +2,17 @@ name: Build and Test CI
 
 on:
   push:
-    branches: [ "main" ]
+    branches:
+      - main
+    paths-ignore:
+      - '**/**.md'
+      - 'docs/**'
   pull_request:
-    branches: [ "main" ]
+    branches:
+      - main
+    paths-ignore:
+      - '**/**.md'
+      - 'docs/**'
 
 permissions:
   contents: read

.github/workflows/codeql.yml

@@ -2,10 +2,17 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ "main" ]
+    branches:
+      - main
+    paths-ignore:
+      - '**/**.md'
+      - 'docs/**'
   pull_request:
-    # The branches below must be a subset of the branches above
-    branches: [ "main" ]
+    branches:
+      - main
+    paths-ignore:
+      - '**/**.md'
+      - 'docs/**'
 
 permissions:
   contents: read

.github/workflows/gh-pages.yml

@@ -0,0 +1,44 @@
+name: Deploy Github Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'README.md'
+      - 'docs/book/**'
+  pull_request:
+     paths:
+      - 'README.md'
+      - 'docs/book/**'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: '0.4.35'
+
+      - run: cd docs/book && mdbook build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/book
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'

.gitignore

@@ -3,4 +3,5 @@
 bin/*
 kind-logs-*
 cover.out
-kubeconfig
+kubeconfig*
+.devbox/*

README.md

@@ -1,67 +1,53 @@
-[![Go Report Card](https://goreportcard.com/badge/github.com/linode/cluster-api-provider-linode)](https://goreportcard.com/report/github.com/linode/cluster-api-provider-linode)
-[![Go Reference](https://pkg.go.dev/badge/github.com/linode/cluster-api-provider-linode.svg)](https://pkg.go.dev/github.com/linode/cluster-api-provider-linode)
-[![Go Build and Test CI](https://github.com/linode/cluster-api-provider-linode/actions/workflows/go-test.yml/badge.svg)](https://github.com/linode/cluster-api-provider-linode/actions/workflows/go-test.yml)
-[![CodeQL](https://github.com/linode/cluster-api-provider-linode/actions/workflows/codeql.yml/badge.svg)](https://github.com/linode/cluster-api-provider-linode/actions/workflows/codeql.yml)
-[![Docker Image Build CI](https://github.com/linode/cluster-api-provider-linode/actions/workflows/build-docker-image.yml/badge.svg)](https://github.com/linode/cluster-api-provider-linode/actions/workflows/build-docker-image.yml)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
-
-
-
 # Cluster API Provider Linode
-A [Cluster API](https://cluster-api.sigs.k8s.io/) implementation for [Linode](https://www.linode.com/) to create kubernetes clusters.
-
-## Local development
-
-### Using Devbox
-
-1. [Download Devbox](https://jetpack.io/devbox/docs/installing_devbox/) 
-2. Install dependent packages in your project 
-   ```shell
-   devbox install
-   ```
-3. Use devbox environment
-   ```shell
-   # use a devbox shell
-   devbox shell
-   # or run a single command in devbox
-   devbox run make tilt-cluster
-   # or leverage direnv integration
-   devbox generate direnv
-   ```
-
-
-### Enable git hooks
 
-To enable automatic code validation on code push, execute the following commands:
+<p align="center">
+<!-- go doc / reference card -->
+<a href="https://pkg.go.dev/github.com/linode/cluster-api-provider-linode">
+<img src="https://pkg.go.dev/badge/github.com/linode/cluster-api-provider-linode.svg"></a>
+<!-- goreportcard badge -->
+<a href="https://goreportcard.com/report/github.com/linode/cluster-api-provider-linode">
+<img src="https://goreportcard.com/badge/github.com/linode/cluster-api-provider-linode"></a>
+<!-- join kubernetes slack channel for linode -->
+<a href="https://kubernetes.slack.com/messages/CD4B15LUR">
+<img src="https://img.shields.io/badge/join%20slack-%23linode-brightgreen"></a>
+<!-- PRs welcome -->
+<a href="http://makeapullrequest.com">
+<img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg"></a>
+</p>
+<p align="center">
+<!-- go build / test CI -->
+<a href="https://github.com/linode/cluster-api-provider-linode/actions/workflows/go-test.yml">
+<img src="https://github.com/linode/cluster-api-provider-linode/actions/workflows/go-test.yml/badge.svg"></a>
+<!-- docker build CI -->
+<a href="https://github.com/linode/cluster-api-provider-linode/actions/workflows/build-docker-image.yml">
+<img src="https://github.com/linode/cluster-api-provider-linode/actions/workflows/build-docker-image.yml/badge.svg"></a>
+<!-- CodeQL -->
+<a href="https://github.com/linode/cluster-api-provider-linode/actions/workflows/codeql.yml">
+<img src="https://github.com/linode/cluster-api-provider-linode/actions/workflows/codeql.yml/badge.svg"></a>
+</p>
 
-```bash
-PATH="$PWD/bin:$PATH" make husky && husky install
-```
+------
 
-If you would like to temporarily disable git hook, set `SKIP_GIT_PUSH_HOOK` value:
+## What is Cluster API Provider Linode (CAPL)
 
-```bash
-SKIP_GIT_PUSH_HOOK=1 git push
-```
+This is a [Cluster API](https://cluster-api.sigs.k8s.io/) implementation for [Linode](https://www.linode.com/)
+to create, configure, and manage Kubernetes clusters.
 
-### Local development with Tilt
+------
 
-For local development execute the following `make` target:
+## Compatibility
 
-```bash
-LINODE_TOKEN=<YOUR LINODE TOKEN> make tilt-cluster
-```
+### Cluster API Versions
+CAPL is compatible only with the `v1beta1` version of CAPI (v1.0.x).
 
-This command creates a Kind cluster, and deploys resources via Tilt. You can freely change the code and wait for Tilt to update provider.
+### Kubernetes Versions
 
-### E2E testing
+CAPL is able to install and manage the [versions of Kubernetes supported by the Cluster API (CAPI) project](https://cluster-api.sigs.k8s.io/reference/versions.html#supported-kubernetes-versions).
 
-For local development execute the following `make` target:
+------
 
-```bash
-LINODE_TOKEN=<YOUR LINODE TOKEN> make e2etest
-```
+## Documentation
 
-This command creates a Kind cluster, and executes all the defined tests.
+Please see our [Book](https://linode.github.io/cluster-api-provider-linode) for in-depth user documentation.
 
-> Please ensure you have increased maximum open files on your host: https://kind.sigs.k8s.io/docs/user/known-issues/#pod-errors-due-to-too-many-open-files
+Additional docs can be found in the [/docs](/docs) directory.

docs/README.md

@@ -0,0 +1,14 @@
+# Documentation Index
+
+## Quick Start
+
+- [Getting started](https://linode.github.io/cluster-api-provider-linode/topics/getting-started.html)
+- [Cluster API quick start](https://cluster-api.sigs.k8s.io/user/quick-start.html)
+
+## Development
+
+- [Development guide](https://linode.github.io/cluster-api-provider-linode/developers/development.html)
+
+## Troubleshooting
+
+- [Troubleshooting guide](ihttps://linode.github.io/cluster-api-provider-linode/topics/troubleshooting.html)

docs/book/.gitignore

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

docs/book/book.toml

@@ -0,0 +1,19 @@
+[book]
+authors = ["Ashley Dumaine"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Cluster API Provider Linode Book"
+
+[build]
+build-dir = "book"
+
+[output.html]
+git-repository-url = "https://github.com/linode/cluster-api-provider-linode"
+additional-css = ["./theme/mdbook-admonish.css"]
+
+[preprocessor]
+
+[preprocessor.admonish]
+command = "mdbook-admonish"
+assets_version = "3.0.2" # do not edit: managed by `mdbook-admonish install`

docs/book/src/SUMMARY.md

@@ -0,0 +1,9 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Topics](./topics/topics.md)
+    - [Getting Started](./topics/getting-started.md)
+    - [Troubleshooting](./topics/troubleshooting.md)
+    - [Addons](./topics/addons.md)
+- [Development](./developers/development.md)
+- [Reference](./reference/reference.md)