Add workflow for a book publishing job

.github/workflows/documentation.yaml

@@ -0,0 +1,36 @@
+name: Documentation
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  gh-pages:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - run: make -C docs/book build
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v1
+      with:
+        path: ./docs/book/book
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: gh-pages
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
+

docs/book/Makefile

@@ -0,0 +1,34 @@
+# Copyright 2023 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.
+TOOLS_DIR := $(realpath ../../hack/tools)
+TOOLS_BIN_DIR := $(TOOLS_DIR)/bin
+BIN_DIR := bin
+MDBOOK_INSTALL := $(realpath ../../scripts/ci-install-mdbook.sh)
+
+export PATH := $(abspath $(TOOLS_BIN_DIR)/bin):$(PATH)
+
+# Only set MDBOOK if it's not set as an environment variable
+MDBOOK ?= $(TOOLS_BIN_DIR)/bin/mdbook
+$(MDBOOK):
+	$(MDBOOK_INSTALL) 0.4.35 $(TOOLS_BIN_DIR)
+
+.PHONY: serve
+serve: $(MDBOOK)
+	$(MDBOOK) serve
+
+.PHONY: build
+build: $(MDBOOK)
+	$(MDBOOK) build

docs/book/book.toml

@@ -0,0 +1,26 @@
+[book]
+language = "en"
+multilingual = false
+src = "src"
+title = "Cluster API Operator"
+description = "Cluster API Operator"
+
+[preprocessor.toc]
+command = "mdbook-toc"
+marker = "[[_TOC_]]"
+
+[preprocessor.fs-summary]
+# (default: true)
+clean-paths = false
+
+# other preprocessors will naturally need to 
+# run after the summary has been generated 
+[preprocessor.links]
+after = ["fs-summary"] 
+
+[output.html]
+mathjax-support = true
+git-repository-url = "https://github.com/kubernetes-sigs/cluster-api-operator"
+git-repository-icon = "fa-github"
+site-url = "/cluster-api-operator/"
+

docs/book/src/01_intro.md

@@ -0,0 +1,8 @@
+# Cluster API Operator
+
+## ✨ What is Cluster API Operator?
+
+The **Cluster API Operator** is a Kubernetes Operator designed to empower cluster administrators to handle the lifecycle of Cluster API providers within a management cluster using a declarative approach. It aims to improve user experience in deploying and managing Cluster API, making it easier to handle day-to-day tasks and automate workflows with GitOps. 
+
+This operator leverages a declarative API and extends the capabilities of the `clusterctl` CLI, allowing greater flexibility and configuration options for cluster administrators. 
+

scripts/ci-install-mdbook.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+
+# Copyright 2023 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.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+VERSION=${1}
+OUTPUT_PATH=${2}
+
+# Ensure the output folder exists
+mkdir -p "${OUTPUT_PATH}"
+
+# Install cargo
+curl https://sh.rustup.rs -sSf | sh -s -- -y
+. "$HOME/.cargo/env"
+
+# Install mdbook and dependencies
+cargo install mdbook --version "$VERSION" --root "$OUTPUT_PATH"
+cargo install mdbook-fs-summary --root "$OUTPUT_PATH"
+cargo install mdbook-toc --root "$OUTPUT_PATH"