Skip to content

Commit 3cad7ae

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #16 from shanduur/docs
docs: initial COSI docs website
2 parents 4347978 + df4e5fa commit 3cad7ae

29 files changed

+1662
-2391
lines changed

‎.github/dependabot.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
version: 2
2+
enable-beta-ecosystems: true
3+
updates:
4+
5+
- package-ecosystem: "gomod"
6+
directory: "/"
7+
schedule:
8+
interval: "weekly"
9+
groups: # batch updates together for fewer dependabot PRs
10+
golang-dependencies:
11+
patterns:
12+
- "github.com/golang*"
13+
- "golang.org/x*"
14+
k8s-dependencies:
15+
patterns:
16+
- "k8s.io*"
17+
- "sigs.k8s.io*"
18+
exclude-patterns:
19+
# controller-runtime has history of breaking API changes more often than other k8s projects
20+
- "sigs.k8s.io/controller-runtime"
21+
github-dependencies:
22+
patterns:
23+
- "github.com*"
24+
25+
- package-ecosystem: "docker"
26+
directory: "/"
27+
schedule:
28+
interval: "weekly"

‎.github/workflows/docs.yaml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Sample workflow for building and deploying a mdBook site to GitHub Pages
2+
#
3+
# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
4+
#
5+
name: Deploy mdBook site to Pages
6+
7+
on:
8+
# Runs on only core version tags
9+
push:
10+
tags:
11+
- 'v*'
12+
- '!v*-alpha*'
13+
- '!v*-beta*'
14+
- '!v*-pre*'
15+
- '!v*-rc*'
16+
17+
# Allows you to run this workflow manually from the Actions tab
18+
workflow_dispatch:
19+
20+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
21+
permissions:
22+
contents: read
23+
pages: write
24+
id-token: write
25+
26+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
27+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
28+
concurrency:
29+
group: "pages"
30+
cancel-in-progress: false
31+
32+
jobs:
33+
# Build job
34+
build:
35+
runs-on: ubuntu-latest
36+
steps:
37+
- uses: actions/checkout@v4
38+
- name: Install mdBook
39+
run: |
40+
make mdbook
41+
- name: Setup Go
42+
uses: actions/setup-go@v5
43+
with:
44+
go-version-file: ./client/go.mod
45+
- name: Setup Pages
46+
id: pages
47+
uses: actions/configure-pages@v5
48+
- name: Build with mdBook
49+
run: |
50+
make build-docs
51+
- name: Upload artifact
52+
uses: actions/upload-pages-artifact@v3
53+
with:
54+
path: ./docs/book
55+
56+
# Deployment job
57+
deploy:
58+
environment:
59+
name: github-pages
60+
url: ${{ steps.deployment.outputs.page_url }}
61+
runs-on: ubuntu-latest
62+
needs: build
63+
steps:
64+
- name: Deploy to GitHub Pages
65+
id: deployment
66+
uses: actions/deploy-pages@v4

‎Makefile‎

Lines changed: 52 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -48,9 +48,14 @@ SIDECAR_TAG ?= cosi-provisioner-sidecar:latest
4848
##@ Development
4949

5050
.PHONY: generate
51-
generate: controller/Dockerfile sidecar/Dockerfile ## Generate files
51+
generate: crd-ref-docs controller/Dockerfile sidecar/Dockerfile ## Generate files
5252
$(MAKE) -C client crds
5353
$(MAKE) -C proto generate
54+
$(CRD_REF_DOCS) \
55+
--config=./docs/.crd-ref-docs.yaml \
56+
--source-path=./client/apis \
57+
--renderer=markdown \
58+
--output-path=./docs/src/api/
5459
%/Dockerfile: hack/Dockerfile.in hack/gen-dockerfile.sh
5560
hack/gen-dockerfile.sh $* > "$@"
5661

@@ -107,6 +112,16 @@ build.controller: controller/Dockerfile ## Build only the controller container i
107112
build.sidecar: sidecar/Dockerfile ## Build only the sidecar container image
108113
$(DOCKER) build --file sidecar/Dockerfile --platform $(PLATFORM) $(BUILD_ARGS) --tag $(SIDECAR_TAG) .
109114

115+
.PHONY: build-docs
116+
build-docs: generate mdbook
117+
cd docs; $(MDBOOK) build
118+
119+
MDBOOK_PORT ?= 3000
120+
121+
.PHONY: serve-docs
122+
serve-docs: generate mdbook build-docs
123+
cd docs; $(MDBOOK) serve --port $(MDBOOK_PORT)
124+
110125
.PHONY: clean
111126
clean: ## Clean build environment
112127
$(MAKE) -C proto clean
@@ -121,11 +136,11 @@ clobber: ## Clean build environment and cached tools
121136

122137
.PHONY: cluster
123138
cluster: kind ctlptl ## Create Kind cluster and local registry
124-
$(CTLPTL) apply -f ctlptl.yaml
139+
PATH=$(TOOLBIN):$(PATH) $(CTLPTL) apply -f ctlptl.yaml
125140

126141
.PHONY: cluster-reset
127142
cluster-reset: kind ctlptl ## Delete Kind cluster
128-
$(CTLPTL) delete -f ctlptl.yaml
143+
PATH=$(TOOLBIN):$(PATH) $(CTLPTL) delete -f ctlptl.yaml
129144

130145
.PHONY: deploy
131146
deploy: kustomize ## Deploy controller to the K8s cluster specified in ~/.kube/config
@@ -145,44 +160,58 @@ $(TOOLBIN):
145160
mkdir -p $(TOOLBIN)
146161

147162
# Tool Binaries
148-
CHAINSAW ?= $(TOOLBIN)/chainsaw
149-
CTLPTL ?= $(TOOLBIN)/ctlptl
163+
CHAINSAW ?= $(TOOLBIN)/chainsaw
164+
CRD_REF_DOCS ?= $(TOOLBIN)/crd-ref-docs
165+
CTLPTL ?= $(TOOLBIN)/ctlptl
150166
GOLANGCI_LINT ?= $(TOOLBIN)/golangci-lint
151-
KIND ?= $(TOOLBIN)/kind
152-
KUSTOMIZE ?= $(TOOLBIN)/kustomize
167+
KIND ?= $(TOOLBIN)/kind
168+
KUSTOMIZE ?= $(TOOLBIN)/kustomize
169+
MDBOOK ?= $(TOOLBIN)/mdbook
153170

154171
# Tool Versions
155-
CHAINSAW_VERSION ?= $(shell grep 'github.com/kyverno/chainsaw ' ./hack/tools/go.mod | cut -d ' ' -f 2)
156-
CTLPTL_VERSION ?= $(shell grep 'github.com/tilt-dev/ctlptl ' ./hack/tools/go.mod | cut -d ' ' -f 2)
157-
GOLANGCI_LINT_VERSION ?= $(shell grep 'github.com/golangci/golangci-lint ' ./hack/tools/go.mod | cut -d ' ' -f 2)
158-
KIND_VERSION ?= $(shell grep 'sigs.k8s.io/kind ' ./hack/tools/go.mod | cut -d ' ' -f 2)
159-
KUSTOMIZE_VERSION ?= $(shell grep 'sigs.k8s.io/kustomize/kustomize/v5 ' ./hack/tools/go.mod | cut -d ' ' -f 2)
172+
CHAINSAW_VERSION ?= v0.2.12
173+
CRD_REF_DOCS_VERSION ?= v0.1.0
174+
CTLPTL_VERSION ?= v0.8.39
175+
GOLANGCI_LINT_VERSION ?= v1.64.7
176+
KIND_VERSION ?= v0.27.0
177+
KUSTOMIZE_VERSION ?= v5.6.0
178+
MDBOOK_VERSION ?= v0.4.47
160179

161180
.PHONY: chainsaw
162-
chainsaw: $(CHAINSAW)$(CHAINSAW_VERSION)
163-
$(CHAINSAW)$(CHAINSAW_VERSION): $(TOOLBIN)
181+
chainsaw: $(CHAINSAW)-$(CHAINSAW_VERSION)
182+
$(CHAINSAW)-$(CHAINSAW_VERSION): $(TOOLBIN)
164183
$(call go-install-tool,$(CHAINSAW),github.com/kyverno/chainsaw,$(CHAINSAW_VERSION))
165184

185+
.PHONY: crd-ref-docs
186+
crd-ref-docs: $(CRD_REF_DOCS)-$(CRD_REF_DOCS_VERSION)
187+
$(CRD_REF_DOCS)-$(CRD_REF_DOCS_VERSION): $(TOOLBIN)
188+
$(call go-install-tool,$(CRD_REF_DOCS),github.com/elastic/crd-ref-docs,$(CRD_REF_DOCS_VERSION))
189+
166190
.PHONY: ctlptl
167-
ctlptl: $(CTLPTL)$(CTLPTL_VERSION)
168-
$(CTLPTL)$(CTLPTL_VERSION): $(TOOLBIN)
191+
ctlptl: $(CTLPTL)-$(CTLPTL_VERSION)
192+
$(CTLPTL)-$(CTLPTL_VERSION): $(TOOLBIN)
169193
$(call go-install-tool,$(CTLPTL),github.com/tilt-dev/ctlptl/cmd/ctlptl,$(CTLPTL_VERSION))
170194

171195
.PHONY: golangci-lint
172-
golangci-lint: $(GOLANGCI_LINT)$(GOLANGCI_LINT_VERSION)
173-
$(GOLANGCI_LINT)$(GOLANGCI_LINT_VERSION): $(TOOLBIN)
174-
$(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/cmd/golangci-lint,$(GOLANGCI_LINT_VERSION))
196+
golangci-lint: $(GOLANGCI_LINT)-$(GOLANGCI_LINT_VERSION)
197+
$(GOLANGCI_LINT)-$(GOLANGCI_LINT_VERSION): $(TOOLBIN)
198+
./hack/tools/install-golangci-lint.sh $(TOOLBIN) $(GOLANGCI_LINT) $(GOLANGCI_LINT_VERSION)
175199

176200
.PHONY: kind
177-
kind: $(KIND)$(KIND_VERSION)
178-
$(KIND)$(KIND_VERSION): $(TOOLBIN)
201+
kind: $(KIND)-$(KIND_VERSION)
202+
$(KIND)-$(KIND_VERSION): $(TOOLBIN)
179203
$(call go-install-tool,$(KIND),sigs.k8s.io/kind,$(KIND_VERSION))
180204

181205
.PHONY: kustomize
182-
kustomize: $(KUSTOMIZE)$(KUSTOMIZE_VERSION)
183-
$(KUSTOMIZE)$(KUSTOMIZE_VERSION): $(TOOLBIN)
206+
kustomize: $(KUSTOMIZE)-$(KUSTOMIZE_VERSION)
207+
$(KUSTOMIZE)-$(KUSTOMIZE_VERSION): $(TOOLBIN)
184208
$(call go-install-tool,$(KUSTOMIZE),sigs.k8s.io/kustomize/kustomize/v5,$(KUSTOMIZE_VERSION))
185209

210+
.PHONY: mdbook
211+
mdbook: $(MDBOOK)-$(MDBOOK_VERSION)
212+
$(MDBOOK)-$(MDBOOK_VERSION): $(TOOLBIN)
213+
./hack/tools/install-mdbook.sh $(MDBOOK) $(MDBOOK_VERSION)
214+
186215
# go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist
187216
# $1 - target path with name of binary
188217
# $2 - package url which can be installed

‎docs/.crd-ref-docs.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
processor:
2+
# RE2 regular expressions describing types that should be excluded from the generated documentation.
3+
ignoreTypes: []
4+
# RE2 regular expressions describing type fields that should be excluded from the generated documentation.
5+
ignoreFields: []
6+
render:
7+
# Version of Kubernetes to use when generating links to Kubernetes API documentation.
8+
kubernetesVersion: '1.32'

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
book
2+
theme/index.hbs

‎docs/book.toml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
[book]
2+
title = "Container Object Storage Interface"
3+
description = "This site documents how to develop and deploy a Container Object Storage Interface (COSI) driver on Kubernetes."
4+
authors = ["The Kubernetes Authors"]
5+
6+
[output.html]
7+
git-repository-url = "https://github.com/kubernetes-sigs/container-object-storage-interface/tree/main/docs"
8+
edit-url-template = "https://github.com/kubernetes-sigs/container-object-storage-interface/tree/main/docs/{path}"
9+
additional-css = ["theme/custom.css"]
10+
theme = "theme"
11+
12+
[preprocessor.generate-version]
13+
renderers = ["html"]
14+
command = """sh -c 'scripts/generate-version.sh'"""

‎docs/scripts/generate-version.sh‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#!/usr/bin/env bash
2+
3+
set -eu
4+
5+
jq ".[1]"
6+
7+
SHA=$(git rev-parse HEAD)
8+
VERSION="Commit: <a target="_blank" href=\"https:\/\/github.com\/kubernetes-sigs\/container-object-storage-interface\/tree\/${SHA}\"><code>${SHA}<\/code><\/a>"
9+
BRANCH=$(git rev-parse --abbrev-ref HEAD)
10+
11+
if [ -n "$BRANCH" ]; then
12+
VERSION="Branch: <a target="_blank" href=\"https:\/\/github.com\/kubernetes-sigs\/container-object-storage-interface\/tree\/${BRANCH}\"><code>${BRANCH}<\/code><\/a> ${VERSION}"
13+
fi
14+
15+
sed "s/VERSION-PLACEHOLDER/${VERSION}/" theme/index-template.hbs > theme/index.hbs

‎docs/src/SUMMARY.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Summary
2+
3+
- [Introduction](./introduction.md)
4+
- [Quick Start](./quick-start.md)
5+
- [Tasks](./operations/tasks.md)
6+
- [Installing COSI Driver](./operations/installing-driver.md)
7+
- [Troubleshooting](./operations/troubleshooting.md)
8+
- [Monitoring](./operations/monitoring.md)
9+
- [Developer guide](./developing/guide.md)
10+
- [Developing "core" COSI](./developing/core.md)
11+
- [Developing a COSI Driver](./developing/drivers.md)
12+
- [Developing client applications](./developing/clients.md)
13+
- [Go](./developing/clients/go.md)
14+
<!-- TODO(guides): add new guides -->
15+
- [Drivers](./drivers.md)
16+
- [API Reference](./api/out.md)

0 commit comments

Comments
 (0)