Merge pull request #34 from Priyankasaggu11929/fix-netlify-mdbook-build

improve mdbook book setup and fix netlify build

Author: k8s-ci-robot

Makefile

@@ -306,3 +306,23 @@ $(GOLANGCI_LINT): # Build golangci-lint from tools folder.
 
 $(GOLANGCI_LINT_KAL): $(GOLANGCI_LINT) # Build golangci-lint-kal from custom configuration.
 	cd $(TOOLS_DIR); $(GOLANGCI_LINT) custom
+
+
+## --------------------------------------
+## Documentation
+## --------------------------------------
+
+##@ docs
+
+MDBOOK_VERSION ?= 0.5.2
+GO_VERSION ?= 1.25.5
+MDBOOK_SCRIPT := $(ROOT_DIR)/docs/book/install-and-build-mdbook.sh
+
+
+.PHONY: docs
+docs: ## Build the mdBook locally using the same script Netlify uses.
+	GO_VERSION=$(GO_VERSION) MDBOOK_VERSION=$(MDBOOK_VERSION) $(MDBOOK_SCRIPT)
+
+.PHONY: docs-serve
+docs-serve: ## Serve mdBook locally.
+	GO_VERSION=$(GO_VERSION) MDBOOK_VERSION=$(MDBOOK_VERSION) $(MDBOOK_SCRIPT) serve docs/book --open

docs/README.md

@@ -0,0 +1,70 @@
+## Documentation (mdBook)
+
+This repository’s documentation is built using [**mdBook**](https://github.com/rust-lang-nursery/mdBook).
+
+Local builds and hosted builds use the same build script [1] to ensure consistent behavior.
+
+## Local documentation workflows
+
+All documentation targets **must be run from the repository root**.
+
+### Available Makefile targets
+
+```bash
+make docs        # Build the mdBook locally using the shared build script
+make docs-serve  # Serve the mdBook locally
+```
+
+## Build script contract
+
+The documentation build is driven by:
+
+```
+docs/book/install-and-build-mdbook.sh
+```
+
+This script defines how mdBook is installed and executed.
+
+### Environment variables
+
+The build relies on the following environment variables:
+
+| Variable         | Description                      |
+| ---------------- | -------------------------------- |
+| `GO_VERSION`     | Go version used during the build |
+| `MDBOOK_VERSION` | mdBook version to install/use    |
+
+
+## Version synchronization requirements
+
+The environment variables used for documentation builds must be kept **consistent across the repository**.
+
+When either `GO_VERSION` or `MDBOOK_VERSION` is changed, the update **must be applied in all of the following locations**:
+
+1. **Makefile**
+   Used for local documentation builds and serving.
+
+2. **`netlify.toml`**
+   Used for hosted and preview builds.
+
+3. **`docs/book/install-and-build-mdbook.sh`**
+   Used as the canonical build script.
+
+## Editing documentation
+
+1. Make changes under:
+
+   ```
+   docs/book/src/
+   ```
+2. Preview changes locally:
+
+   ```bash
+   make docs-serve
+   ```
+3. Commit only source files; generated output is produced during the build.
+
+---
+
+[1] [`docs/book/install-and-build-mdbook.sh`](book/install-and-build-mdbook.sh)
+

docs/book/install-and-build-mdbook.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+
+# Copyright 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.
+#
+# 
+# Note - This script is adapted from https://github.com/kubernetes-sigs/kubebuilder/blob/master/docs/book/install-and-build.sh
+
+set -e
+
+# The following code is required to allow the preview works with an upper go version
+# More info : https://community.netlify.com/t/go-version-1-13/5680
+# Get the directory that this script file is in
+THIS_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+
+cd "$THIS_DIR"
+
+if [[ -n "$(command -v gimme)" ]]; then
+    GO_VERSION=${GO_VERSION:-stable}  # Use the provided GO_VERSION or default to 'stable'
+    eval "$(gimme $GO_VERSION)"
+fi
+echo go version
+
+# detect OS + ARCH for mdBook
+os=$(go env GOOS)
+arch=$(go env GOARCH)
+
+# translate arch to rust's conventions (if we can)
+if [[ ${arch} == "amd64" || ${arch} == "x86" ]]; then
+    arch="x86_64"
+elif [[ ${arch} == "arm64" ]]; then
+    arch="aarch64"
+fi
+
+# translate os to rust's conventions (if we can)
+ext="tar.gz"
+cmd="tar -C /tmp -xzvf"
+case ${os} in
+    windows)
+        target="pc-windows-msvc"
+        ext="zip"
+        cmd="unzip -d /tmp"
+        ;;
+    darwin)
+        target="apple-darwin"
+        ;;
+    linux)
+        # works for linux, too
+        target="unknown-${os}-musl"
+        ;;
+    *)
+        target="unknown-${os}"
+        ;;
+esac
+
+# grab mdbook
+# we hardcode linux/amd64 since rust uses a different naming scheme and it's a pain to tran
+MDBOOK_VERSION=${MDBOOK_VERSION:-"0.5.0"}
+MDBOOK_BASENAME="mdBook-v${MDBOOK_VERSION}-${arch}-${target}"
+MDBOOK_URL="https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/${MDBOOK_BASENAME}.${ext}"
+
+echo "downloading ${MDBOOK_BASENAME}.${ext} from ${MDBOOK_URL}"
+set -x
+curl -fL -o /tmp/mdbook.${ext} "${MDBOOK_URL}"
+${cmd} /tmp/mdbook.${ext}
+chmod +x /tmp/mdbook
+
+verb=${1:-build}
+/tmp/mdbook ${verb}

netlify.toml

@@ -1,14 +1,10 @@
 [build]
   base = "docs/book"
-  command = "mdbook build"
-  publish = "docs/book/book"
-
+  command = "GO_VERSION=1.25.5 MDBOOK_VERSION=0.5.2 ./install-and-build-mdbook.sh"
+  publish = "book"
 
 [context.deploy-preview]
-  command = "mdbook build"
-
-[context.branch-deploy]
-  command = "mdbook build"
+  command = "GO_VERSION=1.25.5 MDBOOK_VERSION=0.5.2 ./install-and-build-mdbook.sh"
 
 [[redirects]]
   from = "/*"