Skip to content

Commit cd08b2e

Browse files
zanetworkerzanetworker
committed
add docs
Signed-off-by: Adel Zaalouk <[email protected]>
1 parent 54fabed commit cd08b2e

File tree

17 files changed

+3122
-19
lines changed

17 files changed

+3122
-19
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'api/**'
8+
- 'docs/**'
9+
- 'crd-ref-docs.config.yaml'
10+
- '.github/workflows/docs.yml'
11+
- 'Makefile'
12+
pull_request:
13+
paths:
14+
- 'api/**'
15+
- 'docs/**'
16+
- 'crd-ref-docs.config.yaml'
17+
- '.github/workflows/docs.yml'
18+
- 'Makefile'
19+
20+
env:
21+
GO_VERSION: '1.21'
22+
PYTHON_VERSION: '3.11'
23+
24+
jobs:
25+
build-docs:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v4
30+
31+
- name: Setup Go
32+
uses: actions/setup-go@v4
33+
with:
34+
go-version: ${{ env.GO_VERSION }}
35+
36+
- name: Setup Python
37+
uses: actions/setup-python@v4
38+
with:
39+
python-version: ${{ env.PYTHON_VERSION }}
40+
41+
- name: Cache Go modules
42+
uses: actions/cache@v3
43+
with:
44+
path: ~/go/pkg/mod
45+
key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
46+
restore-keys: |
47+
${{ runner.os }}-go-
48+
49+
- name: Cache Python dependencies
50+
uses: actions/cache@v3
51+
with:
52+
path: ~/.cache/pip
53+
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
54+
restore-keys: |
55+
${{ runner.os }}-pip-
56+
57+
- name: Install Go dependencies
58+
run: |
59+
make crd-ref-docs gen-crd-api-reference-docs
60+
61+
- name: Install Python dependencies
62+
run: |
63+
pip install -r docs/requirements.txt
64+
65+
- name: Generate API documentation
66+
run: |
67+
make api-docs
68+
69+
- name: Build documentation site
70+
run: |
71+
make docs-build
72+
73+
- name: Upload documentation artifacts
74+
uses: actions/upload-artifact@v3
75+
with:
76+
name: documentation-site
77+
path: docs/site/
78+
retention-days: 30
79+
80+
- name: Upload API documentation
81+
uses: actions/upload-artifact@v3
82+
with:
83+
name: api-documentation
84+
path: docs/content/reference/api.md
85+
retention-days: 30
86+
87+
deploy-preview:
88+
if: github.event_name == 'pull_request'
89+
needs: build-docs
90+
runs-on: ubuntu-latest
91+
steps:
92+
- name: Checkout
93+
uses: actions/checkout@v4
94+
95+
- name: Download documentation artifacts
96+
uses: actions/download-artifact@v3
97+
with:
98+
name: documentation-site
99+
path: docs/site/
100+
101+
- name: Deploy to Cloudflare Pages (Preview)
102+
uses: cloudflare/pages-action@v1
103+
with:
104+
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
105+
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
106+
projectName: llamastack-k8s-operator-docs
107+
directory: docs/site
108+
gitHubToken: ${{ secrets.GITHUB_TOKEN }}
109+
110+
deploy-production:
111+
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
112+
needs: build-docs
113+
runs-on: ubuntu-latest
114+
steps:
115+
- name: Checkout
116+
uses: actions/checkout@v4
117+
118+
- name: Download documentation artifacts
119+
uses: actions/download-artifact@v3
120+
with:
121+
name: documentation-site
122+
path: docs/site/
123+
124+
- name: Deploy to Cloudflare Pages (Production)
125+
uses: cloudflare/pages-action@v1
126+
with:
127+
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
128+
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
129+
projectName: llamastack-k8s-operator-docs
130+
directory: docs/site
131+
gitHubToken: ${{ secrets.GITHUB_TOKEN }}
132+
wranglerVersion: '3'
133+
134+
- name: Update legacy API docs (backward compatibility)
135+
run: |
136+
make api-docs-legacy
137+
138+
- name: Commit updated API docs
139+
if: github.ref == 'refs/heads/main'
140+
run: |
141+
git config --local user.email "[email protected]"
142+
git config --local user.name "GitHub Action"
143+
git add docs/api-overview.md || true
144+
git diff --staged --quiet || git commit -m "docs: update API documentation [skip ci]"
145+
git push || true
146+
147+
validate-docs:
148+
runs-on: ubuntu-latest
149+
steps:
150+
- name: Checkout
151+
uses: actions/checkout@v4
152+
153+
- name: Setup Python
154+
uses: actions/setup-python@v4
155+
with:
156+
python-version: ${{ env.PYTHON_VERSION }}
157+
158+
- name: Install dependencies
159+
run: |
160+
pip install -r docs/requirements.txt
161+
pip install linkchecker
162+
163+
- name: Validate MkDocs configuration
164+
run: |
165+
cd docs && mkdocs build --strict
166+
167+
- name: Check for broken links (if built)
168+
run: |
169+
if [ -d "docs/site" ]; then
170+
cd docs/site
171+
python -m http.server 8000 &
172+
sleep 5
173+
linkchecker http://localhost:8000 --check-extern || true
174+
kill %1
175+
fi
176+
177+
security-scan:
178+
runs-on: ubuntu-latest
179+
steps:
180+
- name: Checkout
181+
uses: actions/checkout@v4
182+
183+
- name: Run Trivy vulnerability scanner
184+
uses: aquasecurity/trivy-action@master
185+
with:
186+
scan-type: 'fs'
187+
scan-ref: 'docs/'
188+
format: 'sarif'
189+
output: 'trivy-results.sarif'
190+
191+
- name: Upload Trivy scan results
192+
uses: github/codeql-action/upload-sarif@v2
193+
if: always()
194+
with:
195+
sarif_file: 'trivy-results.sarif'

‎.gitignore‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,26 @@ testbin/*
2626
.golangci.mktmp.yml
2727

2828
.DS_Store
29+
30+
# Documentation build artifacts
31+
docs/site/
32+
docs/content/reference/api.md
33+
34+
# Python virtual environments and cache (for MkDocs)
35+
docs/.venv/
36+
docs/venv/
37+
docs/__pycache__/
38+
*.pyc
39+
*.pyo
40+
41+
# MkDocs temporary files
42+
docs/.mkdocs_cache/
43+
44+
# Wrangler/Cloudflare Pages
45+
.wrangler/
46+
wrangler.toml.bak
47+
48+
# Documentation tool binaries (specific to our setup)
49+
bin/crd-ref-docs*
50+
bin/gen-crd-api-reference-docs*
51+
DOCUMENTATION_STRUCTURE.md

‎Makefile‎

Lines changed: 48 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,7 @@ ENVTEST ?= $(LOCALBIN)/setup-envtest
223223
GOLANGCI_LINT ?= $(LOCALBIN)/golangci-lint
224224
YQ ?= $(LOCALBIN)/yq
225225
CRD_REF_DOCS ?= $(LOCALBIN)/crd-ref-docs
226+
GEN_CRD_API_REF_DOCS ?= $(LOCALBIN)/gen-crd-api-reference-docs
226227

227228
## Tool Versions
228229
KUSTOMIZE_VERSION ?= v5.4.3
@@ -231,6 +232,7 @@ ENVTEST_VERSION ?= release-0.19
231232
GOLANGCI_LINT_VERSION ?= v1.64.4
232233
YQ_VERSION ?= v4.45.3
233234
CRD_REF_DOCS_VERSION = v0.1.0
235+
GEN_CRD_API_REF_DOCS_VERSION = v0.3.0
234236

235237
.PHONY: kustomize
236238
kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
@@ -262,6 +264,11 @@ crd-ref-docs: $(CRD_REF_DOCS) ## Download crd-ref-docs locally if necessary.
262264
$(CRD_REF_DOCS): $(LOCALBIN)
263265
$(call go-install-tool,$(CRD_REF_DOCS),github.com/elastic/crd-ref-docs,$(CRD_REF_DOCS_VERSION))
264266

267+
.PHONY: gen-crd-api-reference-docs
268+
gen-crd-api-reference-docs: $(GEN_CRD_API_REF_DOCS) ## Download gen-crd-api-reference-docs locally if necessary.
269+
$(GEN_CRD_API_REF_DOCS): $(LOCALBIN)
270+
$(call go-install-tool,$(GEN_CRD_API_REF_DOCS),github.com/ahmetb/gen-crd-api-reference-docs,$(GEN_CRD_API_REF_DOCS_VERSION))
271+
265272
# go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist
266273
# $1 - target path with name of binary
267274
# $2 - package url which can be installed
@@ -295,10 +302,13 @@ OPERATOR_SDK = $(shell which operator-sdk)
295302
endif
296303
endif
297304

305+
##@ Documentation
306+
298307
.PHONY: api-docs
299-
API_DOCS_PATH = ./docs/api-overview.md
300-
api-docs: crd-ref-docs ## Creates API docs using https://github.com/elastic/crd-ref-docs
301-
mkdir -p docs
308+
API_DOCS_PATH = ./docs/content/reference/api.md
309+
api-docs: crd-ref-docs gen-crd-api-reference-docs ## Generate comprehensive API documentation (HyperShift-style)
310+
mkdir -p docs/content/reference
311+
@echo "Generating API documentation..."
302312
$(CRD_REF_DOCS) --source-path ./ --output-path $(API_DOCS_PATH) --renderer markdown --config ./crd-ref-docs.config.yaml
303313
@# Combined command to remove .io links, ensure a trailing newline, and collapse multiple blank lines.
304314
@sed -i.bak -e '/\.io\/[^v][^1].*)/d' -e '/^$$/N;/^\n$$/D' $(API_DOCS_PATH)
@@ -308,6 +318,41 @@ api-docs: crd-ref-docs ## Creates API docs using https://github.com/elastic/crd-
308318
sed -i.bak -e '$${/^$$/d}' -e '$${N;/^\n$$/d}' $(API_DOCS_PATH); \
309319
fi
310320
rm -f $(API_DOCS_PATH).bak
321+
@echo "API documentation generated at $(API_DOCS_PATH)"
322+
323+
.PHONY: docs-build
324+
docs-build: api-docs ## Build complete documentation site
325+
@echo "Building documentation site..."
326+
@if [ ! -f docs/requirements.txt ]; then echo "Error: docs/requirements.txt not found"; exit 1; fi
327+
@if command -v pip >/dev/null 2>&1; then \
328+
pip install -r docs/requirements.txt; \
329+
else \
330+
echo "Warning: pip not found, assuming dependencies are installed"; \
331+
fi
332+
cd docs && mkdocs build
333+
@echo "Documentation site built in docs/site/"
334+
335+
.PHONY: docs-serve
336+
docs-serve: docs-build ## Serve documentation locally (like HyperShift's serve-containerized)
337+
@echo "Starting documentation server at http://localhost:8000"
338+
cd docs && mkdocs serve --dev-addr 0.0.0.0:8000
339+
340+
.PHONY: docs-clean
341+
docs-clean: ## Clean documentation build artifacts
342+
rm -rf docs/site/
343+
rm -f docs/content/reference/api.md
344+
345+
# Legacy target for backward compatibility
346+
.PHONY: api-docs-legacy
347+
API_DOCS_LEGACY_PATH = ./docs/api-overview.md
348+
api-docs-legacy: crd-ref-docs ## Creates legacy API docs (backward compatibility)
349+
mkdir -p docs
350+
$(CRD_REF_DOCS) --source-path ./ --output-path $(API_DOCS_LEGACY_PATH) --renderer markdown --config ./crd-ref-docs.config.yaml
351+
@sed -i.bak -e '/\.io\/[^v][^1].*)/d' -e '/^$$/N;/^\n$$/D' $(API_DOCS_LEGACY_PATH)
352+
@if sed --version >/dev/null 2>&1; then \
353+
sed -i.bak -e '$${/^$$/d}' -e '$${N;/^\n$$/d}' $(API_DOCS_LEGACY_PATH); \
354+
fi
355+
rm -f $(API_DOCS_LEGACY_PATH).bak
311356

312357
.PHONY: bundle
313358
bundle: manifests kustomize operator-sdk ## Generate bundle manifests and metadata, then validate generated files.

‎crd-ref-docs.config.yaml‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,32 @@ render:
33
# RE2 regular expressions describing types that should be excluded from the generated documentation.
44
ignoreTypes:
55
- "(LlamaStackDistribution)List$"
6-
7-
# Version of Kubernetes to use when generating links to Kubernetes API documentation.
6+
- ".*Status$"
7+
# Add custom type mappings
8+
typeDisplayNamePrefixOverrides:
9+
"github.com/llamastack/llama-stack-k8s-operator/api/v1alpha1": ""
10+
11+
# Enhanced rendering options
812
kubernetesVersion: 1.31
13+
markdownDisabled: false
14+
frontMatter:
15+
title: "API Reference"
16+
description: "Complete API reference for LlamaStack Kubernetes Operator"
17+
weight: 100
18+
19+
# Custom sections
20+
sections:
21+
- title: "Overview"
22+
content: |
23+
This document contains the API reference for the LlamaStack Kubernetes Operator.
24+
The operator manages LlamaStack distributions in Kubernetes clusters.
25+
26+
## Quick Links
27+
28+
- [LlamaStackDistribution](#llamastackdistribution) - Main resource for deploying LlamaStack
29+
- [Getting Started Guide](../getting-started/quick-start/) - Quick start tutorial
30+
- [Examples](../examples/) - Real-world configuration examples
31+
32+
- title: "Resource Types"
33+
content: |
34+
The LlamaStack Operator defines the following Kubernetes custom resources:

0 commit comments

Comments
 (0)