Merge pull request #331 from Danil-Grigorev/book-initial-structure

✨ 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"