docs: initial COSI docs website

.github/dependabot.yml

@@ -0,0 +1,28 @@
+version: 2
+enable-beta-ecosystems: true
+updates:
+
+  - package-ecosystem: "gomod"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups: # batch updates together for fewer dependabot PRs
+      golang-dependencies:
+        patterns:
+          - "github.com/golang*"
+          - "golang.org/x*"
+      k8s-dependencies:
+        patterns:
+          - "k8s.io*"
+          - "sigs.k8s.io*"
+        exclude-patterns:
+          # controller-runtime has history of breaking API changes more often than other k8s projects
+          - "sigs.k8s.io/controller-runtime"
+      github-dependencies:
+        patterns:
+          - "github.com*"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/docs.yaml

@@ -0,0 +1,66 @@
+# Sample workflow for building and deploying a mdBook site to GitHub Pages
+#
+# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
+#
+name: Deploy mdBook site to Pages
+
+on:
+  # Runs on only core version tags
+  push:
+    tags:
+      - 'v*'
+      - '!v*-alpha*'
+      - '!v*-beta*'
+      - '!v*-pre*'
+      - '!v*-rc*'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install mdBook
+        run: |
+          make mdbook
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: ./client/go.mod
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Build with mdBook
+        run: |
+          make build-docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/book
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

Makefile

@@ -48,9 +48,14 @@ SIDECAR_TAG ?= cosi-provisioner-sidecar:latest
 ##@ Development
 
 .PHONY: generate
-generate: controller/Dockerfile sidecar/Dockerfile ## Generate files
+generate: crd-ref-docs controller/Dockerfile sidecar/Dockerfile ## Generate files
 	$(MAKE) -C client crds
 	$(MAKE) -C proto generate
+	$(CRD_REF_DOCS) \
+		--config=./docs/.crd-ref-docs.yaml \
+		--source-path=./client/apis \
+		--renderer=markdown \
+		--output-path=./docs/src/api/
 %/Dockerfile: hack/Dockerfile.in hack/gen-dockerfile.sh
 	hack/gen-dockerfile.sh $* > "$@"
 
@@ -107,6 +112,16 @@ build.controller: controller/Dockerfile ## Build only the controller container i
 build.sidecar: sidecar/Dockerfile ## Build only the sidecar container image
 	$(DOCKER) build --file sidecar/Dockerfile --platform $(PLATFORM) $(BUILD_ARGS) --tag $(SIDECAR_TAG) .
 
+.PHONY: build-docs
+build-docs: generate mdbook
+	cd docs; $(MDBOOK) build
+
+MDBOOK_PORT ?= 3000
+
+.PHONY: serve-docs
+serve-docs: generate mdbook build-docs
+	cd docs; $(MDBOOK) serve --port $(MDBOOK_PORT)
+
 .PHONY: clean
 clean: ## Clean build environment
 	$(MAKE) -C proto clean
@@ -121,11 +136,11 @@ clobber: ## Clean build environment and cached tools
 
 .PHONY: cluster
 cluster: kind ctlptl ## Create Kind cluster and local registry
-	$(CTLPTL) apply -f ctlptl.yaml
+	PATH=$(TOOLBIN):$(PATH) $(CTLPTL) apply -f ctlptl.yaml
 
 .PHONY: cluster-reset
 cluster-reset: kind ctlptl ## Delete Kind cluster
-	$(CTLPTL) delete -f ctlptl.yaml
+	PATH=$(TOOLBIN):$(PATH) $(CTLPTL) delete -f ctlptl.yaml
 
 .PHONY: deploy
 deploy: kustomize ## Deploy controller to the K8s cluster specified in ~/.kube/config
@@ -145,44 +160,58 @@ $(TOOLBIN):
 	mkdir -p $(TOOLBIN)
 
 # Tool Binaries
-CHAINSAW ?= $(TOOLBIN)/chainsaw
-CTLPTL ?= $(TOOLBIN)/ctlptl
+CHAINSAW      ?= $(TOOLBIN)/chainsaw
+CRD_REF_DOCS  ?= $(TOOLBIN)/crd-ref-docs
+CTLPTL        ?= $(TOOLBIN)/ctlptl
 GOLANGCI_LINT ?= $(TOOLBIN)/golangci-lint
-KIND ?= $(TOOLBIN)/kind
-KUSTOMIZE ?= $(TOOLBIN)/kustomize
+KIND          ?= $(TOOLBIN)/kind
+KUSTOMIZE     ?= $(TOOLBIN)/kustomize
+MDBOOK        ?= $(TOOLBIN)/mdbook
 
 # Tool Versions
-CHAINSAW_VERSION ?= $(shell grep 'github.com/kyverno/chainsaw ' ./hack/tools/go.mod | cut -d ' ' -f 2)
-CTLPTL_VERSION ?= $(shell grep 'github.com/tilt-dev/ctlptl ' ./hack/tools/go.mod | cut -d ' ' -f 2)
-GOLANGCI_LINT_VERSION ?= $(shell grep 'github.com/golangci/golangci-lint ' ./hack/tools/go.mod | cut -d ' ' -f 2)
-KIND_VERSION ?= $(shell grep 'sigs.k8s.io/kind ' ./hack/tools/go.mod | cut -d ' ' -f 2)
-KUSTOMIZE_VERSION ?= $(shell grep 'sigs.k8s.io/kustomize/kustomize/v5 ' ./hack/tools/go.mod | cut -d ' ' -f 2)
+CHAINSAW_VERSION      ?= v0.2.12
+CRD_REF_DOCS_VERSION  ?= v0.1.0
+CTLPTL_VERSION        ?= v0.8.39
+GOLANGCI_LINT_VERSION ?= v1.64.7
+KIND_VERSION          ?= v0.27.0
+KUSTOMIZE_VERSION     ?= v5.6.0
+MDBOOK_VERSION        ?= v0.4.47
 
 .PHONY: chainsaw
-chainsaw: $(CHAINSAW)$(CHAINSAW_VERSION)
-$(CHAINSAW)$(CHAINSAW_VERSION): $(TOOLBIN)
+chainsaw: $(CHAINSAW)-$(CHAINSAW_VERSION)
+$(CHAINSAW)-$(CHAINSAW_VERSION): $(TOOLBIN)
 	$(call go-install-tool,$(CHAINSAW),github.com/kyverno/chainsaw,$(CHAINSAW_VERSION))
 
+.PHONY: crd-ref-docs
+crd-ref-docs: $(CRD_REF_DOCS)-$(CRD_REF_DOCS_VERSION)
+$(CRD_REF_DOCS)-$(CRD_REF_DOCS_VERSION): $(TOOLBIN)
+	$(call go-install-tool,$(CRD_REF_DOCS),github.com/elastic/crd-ref-docs,$(CRD_REF_DOCS_VERSION))
+
 .PHONY: ctlptl
-ctlptl: $(CTLPTL)$(CTLPTL_VERSION)
-$(CTLPTL)$(CTLPTL_VERSION): $(TOOLBIN)
+ctlptl: $(CTLPTL)-$(CTLPTL_VERSION)
+$(CTLPTL)-$(CTLPTL_VERSION): $(TOOLBIN)
 	$(call go-install-tool,$(CTLPTL),github.com/tilt-dev/ctlptl/cmd/ctlptl,$(CTLPTL_VERSION))
 
 .PHONY: golangci-lint
-golangci-lint: $(GOLANGCI_LINT)$(GOLANGCI_LINT_VERSION)
-$(GOLANGCI_LINT)$(GOLANGCI_LINT_VERSION): $(TOOLBIN)
-	$(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/cmd/golangci-lint,$(GOLANGCI_LINT_VERSION))
+golangci-lint: $(GOLANGCI_LINT)-$(GOLANGCI_LINT_VERSION)
+$(GOLANGCI_LINT)-$(GOLANGCI_LINT_VERSION): $(TOOLBIN)
+	./hack/tools/install-golangci-lint.sh $(TOOLBIN) $(GOLANGCI_LINT) $(GOLANGCI_LINT_VERSION)
 
 .PHONY: kind
-kind: $(KIND)$(KIND_VERSION)
-$(KIND)$(KIND_VERSION): $(TOOLBIN)
+kind: $(KIND)-$(KIND_VERSION)
+$(KIND)-$(KIND_VERSION): $(TOOLBIN)
 	$(call go-install-tool,$(KIND),sigs.k8s.io/kind,$(KIND_VERSION))
 
 .PHONY: kustomize
-kustomize: $(KUSTOMIZE)$(KUSTOMIZE_VERSION)
-$(KUSTOMIZE)$(KUSTOMIZE_VERSION): $(TOOLBIN)
+kustomize: $(KUSTOMIZE)-$(KUSTOMIZE_VERSION)
+$(KUSTOMIZE)-$(KUSTOMIZE_VERSION): $(TOOLBIN)
 	$(call go-install-tool,$(KUSTOMIZE),sigs.k8s.io/kustomize/kustomize/v5,$(KUSTOMIZE_VERSION))
 
+.PHONY: mdbook
+mdbook: $(MDBOOK)-$(MDBOOK_VERSION)
+$(MDBOOK)-$(MDBOOK_VERSION): $(TOOLBIN)
+	./hack/tools/install-mdbook.sh $(MDBOOK) $(MDBOOK_VERSION)
+
 # go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist
 # $1 - target path with name of binary
 # $2 - package url which can be installed

docs/.crd-ref-docs.yaml

@@ -0,0 +1,8 @@
+processor:
+  # RE2 regular expressions describing types that should be excluded from the generated documentation.
+  ignoreTypes: []
+  # RE2 regular expressions describing type fields that should be excluded from the generated documentation.
+  ignoreFields: []
+render:
+  # Version of Kubernetes to use when generating links to Kubernetes API documentation.
+  kubernetesVersion: '1.32'

docs/.gitignore

@@ -0,0 +1,2 @@
+book
+theme/index.hbs

docs/book.toml

@@ -0,0 +1,14 @@
+[book]
+title = "Container Object Storage Interface"
+description = "This site documents how to develop and deploy a Container Object Storage Interface (COSI) driver on Kubernetes."
+authors = ["The Kubernetes Authors"]
+
+[output.html]
+git-repository-url = "https://github.com/kubernetes-sigs/container-object-storage-interface/tree/main/docs"
+edit-url-template = "https://github.com/kubernetes-sigs/container-object-storage-interface/tree/main/docs/{path}"
+additional-css = ["theme/custom.css"]
+theme = "theme"
+
+[preprocessor.generate-version]
+renderers = ["html"]
+command = """sh -c 'scripts/generate-version.sh'"""

docs/scripts/generate-version.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+set -eu
+
+jq ".[1]"
+
+SHA=$(git rev-parse HEAD)
+VERSION="Commit: <a target="_blank" href=\"https:\/\/github.com\/kubernetes-sigs\/container-object-storage-interface\/tree\/${SHA}\"><code>${SHA}<\/code><\/a>"
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+if [ -n "$BRANCH" ]; then
+  VERSION="Branch: <a target="_blank" href=\"https:\/\/github.com\/kubernetes-sigs\/container-object-storage-interface\/tree\/${BRANCH}\"><code>${BRANCH}<\/code><\/a> ${VERSION}"
+fi
+
+sed "s/VERSION-PLACEHOLDER/${VERSION}/" theme/index-template.hbs > theme/index.hbs

docs/src/SUMMARY.md

@@ -0,0 +1,16 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Quick Start](./quick-start.md)
+- [Tasks](./operations/tasks.md)
+  - [Installing COSI Driver](./operations/installing-driver.md)
+  - [Troubleshooting](./operations/troubleshooting.md)
+  - [Monitoring](./operations/monitoring.md)
+- [Developer guide](./developing/guide.md)
+  - [Developing "core" COSI](./developing/core.md)
+  - [Developing a COSI Driver](./developing/drivers.md)
+  - [Developing client applications](./developing/clients.md)
+    - [Go](./developing/clients/go.md)
+    <!-- TODO(guides): add new guides -->
+- [Drivers](./drivers.md)
+- [API Reference](./api/out.md)