Title: Add documentation website for Llama Stack Kubernetes operator

.github/workflows/docs.yml

@@ -0,0 +1,196 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    paths: 
+      - 'api/**'
+      - 'docs/**'
+      - 'crd-ref-docs.config.yaml'
+      - '.github/workflows/docs.yml'
+      - 'Makefile'
+  pull_request:
+    paths:
+      - 'api/**'
+      - 'docs/**'
+      - 'crd-ref-docs.config.yaml'
+      - '.github/workflows/docs.yml'
+      - 'Makefile'
+
+env:
+  GO_VERSION: '1.21'
+  PYTHON_VERSION: '3.11'
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Cache Go modules
+        uses: actions/cache@v3
+        with:
+          path: ~/go/pkg/mod
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+
+      - name: Cache Python dependencies
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install Go dependencies
+        run: |
+          make crd-ref-docs gen-crd-api-reference-docs
+
+      - name: Install Python dependencies
+        run: |
+          pip install -r docs/requirements.txt
+
+      - name: Generate API documentation
+        run: |
+          make api-docs
+
+      - name: Build documentation site
+        run: |
+          make docs-build
+
+      - name: Upload documentation artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation-site
+          path: docs/site/
+          retention-days: 30
+
+      - name: Upload API documentation
+        uses: actions/upload-artifact@v4
+        with:
+          name: api-documentation
+          path: docs/content/reference/api.md
+          retention-days: 30
+
+  deploy-preview:
+    if: github.event_name == 'pull_request'
+    needs: build-docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download documentation artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: documentation-site
+          path: docs/site/
+
+      - name: Deploy to Cloudflare Pages (Preview)
+        uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: llamastack-k8s-operator-docs
+          directory: docs/site
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
+          wranglerVersion: '3'
+
+  deploy-production:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build-docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download documentation artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: documentation-site
+          path: docs/site/
+
+      - name: Deploy to Cloudflare Pages (Production)
+        uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: llamastack-k8s-operator-docs
+          directory: docs/site
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
+          wranglerVersion: '3'
+
+      - name: Update legacy API docs (backward compatibility)
+        run: |
+          make api-docs || echo "Legacy API docs target not found, skipping"
+
+      - name: Commit updated API docs
+        if: github.ref == 'refs/heads/main'
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add docs/api-overview.md || true
+          git diff --staged --quiet || git commit -m "docs: update API documentation [skip ci]"
+          git push || true
+
+  validate-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install dependencies
+        run: |
+          pip install -r docs/requirements.txt
+          pip install linkchecker
+
+      - name: Validate MkDocs configuration
+        run: |
+          cd docs && mkdocs build --clean --verbose
+
+      - name: Check for broken links (if built)
+        run: |
+          if [ -d "docs/site" ]; then
+            cd docs/site
+            python -m http.server 8000 &
+            sleep 5
+            linkchecker http://localhost:8000 --no-warnings --ignore-url=".*\.css$" --ignore-url=".*\.js$" || true
+            kill %1 2>/dev/null || true
+          fi
+
+  security-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run Trivy vulnerability scanner
+        uses: aquasecurity/trivy-action@master
+        with:
+          scan-type: 'fs'
+          scan-ref: 'docs/'
+          format: 'sarif'
+          output: 'trivy-results.sarif'
+
+      - name: Upload Trivy scan results
+        uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: 'trivy-results.sarif'

.gitignore

@@ -34,3 +34,26 @@ catalog-item
 config/manifests/bases/llama-stack-k8s-operator.clusterserviceversion.yaml
 
 .DS_Store
+
+# Documentation build artifacts
+docs/site/
+docs/content/reference/api.md
+
+# Python virtual environments and cache (for MkDocs)
+docs/.venv/
+docs/venv/
+docs/__pycache__/
+*.pyc
+*.pyo
+
+# MkDocs temporary files
+docs/.mkdocs_cache/
+
+# Wrangler/Cloudflare Pages
+.wrangler/
+wrangler.toml.bak
+
+# Documentation tool binaries (specific to our setup)
+bin/crd-ref-docs*
+bin/gen-crd-api-reference-docs*
+DOCUMENTATION_STRUCTURE.md

Makefile

@@ -244,6 +244,7 @@ GOLANGCI_LINT ?= $(LOCALBIN)/golangci-lint
 YQ ?= $(LOCALBIN)/yq
 YAMLFMT ?= $(LOCALBIN)/yamlfmt
 CRD_REF_DOCS ?= $(LOCALBIN)/crd-ref-docs
+GEN_CRD_API_REF_DOCS ?= $(LOCALBIN)/gen-crd-api-reference-docs
 
 ## Tool Versions
 KUSTOMIZE_VERSION ?= v5.4.3
@@ -253,6 +254,7 @@ GOLANGCI_LINT_VERSION ?= v1.64.4
 YQ_VERSION ?= v4.45.3
 YAMLFMT_VERSION ?= v0.12.0
 CRD_REF_DOCS_VERSION = v0.2.0
+GEN_CRD_API_REF_DOCS_VERSION = v0.3.0
 
 .PHONY: kustomize
 kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
@@ -289,6 +291,11 @@ crd-ref-docs: $(CRD_REF_DOCS) ## Download crd-ref-docs locally if necessary.
 $(CRD_REF_DOCS): $(LOCALBIN)
 	$(call go-install-tool,$(CRD_REF_DOCS),github.com/elastic/crd-ref-docs,$(CRD_REF_DOCS_VERSION))
 
+.PHONY: gen-crd-api-reference-docs
+gen-crd-api-reference-docs: $(GEN_CRD_API_REF_DOCS) ## Download gen-crd-api-reference-docs locally if necessary.
+$(GEN_CRD_API_REF_DOCS): $(LOCALBIN)
+	$(call go-install-tool,$(GEN_CRD_API_REF_DOCS),github.com/ahmetb/gen-crd-api-reference-docs,$(GEN_CRD_API_REF_DOCS_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
@@ -338,10 +345,13 @@ OPERATOR_SDK = $(shell which operator-sdk)
 endif
 endif
 
+##@ Documentation
+
 .PHONY: api-docs
-API_DOCS_PATH = ./docs/api-overview.md
-api-docs: crd-ref-docs ## Creates API docs using https://github.com/elastic/crd-ref-docs
-	mkdir -p docs
+API_DOCS_PATH = ./docs/content/reference/api.md
+api-docs: crd-ref-docs gen-crd-api-reference-docs ## Generate comprehensive API documentation (HyperShift-style)
+	mkdir -p docs/content/reference
+	@echo "Generating API documentation..."
 	$(CRD_REF_DOCS) --source-path ./ --output-path $(API_DOCS_PATH) --renderer markdown --config ./crd-ref-docs.config.yaml
 	@# Combined command to remove .io links, ensure a trailing newline, and collapse multiple blank lines.
 	@sed -i.bak -e  '/^$$/N;/^\n$$/D' $(API_DOCS_PATH)
@@ -351,6 +361,41 @@ api-docs: crd-ref-docs ## Creates API docs using https://github.com/elastic/crd-
 		sed -i.bak -e '$${/^$$/d}' -e '$${N;/^\n$$/d}' $(API_DOCS_PATH); \
 	fi
 	rm -f $(API_DOCS_PATH).bak
+	@echo "API documentation generated at $(API_DOCS_PATH)"
+
+.PHONY: docs-build
+docs-build: api-docs ## Build complete documentation site
+	@echo "Building documentation site..."
+	@if [ ! -f docs/requirements.txt ]; then echo "Error: docs/requirements.txt not found"; exit 1; fi
+	@if command -v pip >/dev/null 2>&1; then \
+		pip install -r docs/requirements.txt; \
+	else \
+		echo "Warning: pip not found, assuming dependencies are installed"; \
+	fi
+	cd docs && mkdocs build
+	@echo "Documentation site built in docs/site/"
+
+.PHONY: docs-serve
+docs-serve: docs-build ## Serve documentation locally (like HyperShift's serve-containerized)
+	@echo "Starting documentation server at http://localhost:8000"
+	cd docs && mkdocs serve --dev-addr 0.0.0.0:8000
+
+.PHONY: docs-clean
+docs-clean: ## Clean documentation build artifacts
+	rm -rf docs/site/
+	rm -f docs/content/reference/api.md
+
+# Legacy target for backward compatibility
+.PHONY: api-docs-legacy
+API_DOCS_LEGACY_PATH = ./docs/api-overview.md
+api-docs-legacy: crd-ref-docs ## Creates legacy API docs (backward compatibility)
+	mkdir -p docs
+	$(CRD_REF_DOCS) --source-path ./ --output-path $(API_DOCS_LEGACY_PATH) --renderer markdown --config ./crd-ref-docs.config.yaml
+	@sed -i.bak -e '/\.io\/[^v][^1].*)/d' -e '/^$$/N;/^\n$$/D' $(API_DOCS_LEGACY_PATH)
+	@if sed --version >/dev/null 2>&1; then \
+		sed -i.bak -e '$${/^$$/d}' -e '$${N;/^\n$$/d}' $(API_DOCS_LEGACY_PATH); \
+	fi
+	rm -f $(API_DOCS_LEGACY_PATH).bak
 
 .PHONY: bundle
 bundle: manifests kustomize operator-sdk ## Generate bundle manifests and metadata, then validate generated files.

crd-ref-docs.config.yaml

@@ -3,6 +3,32 @@ render:
     # RE2 regular expressions describing types that should be excluded from the generated documentation.
     ignoreTypes:
       - "(LlamaStackDistribution)List$"
-
-  # Version of Kubernetes to use when generating links to Kubernetes API documentation.
+      - ".*Status$"
+    # Add custom type mappings
+    typeDisplayNamePrefixOverrides:
+      "github.com/llamastack/llama-stack-k8s-operator/api/v1alpha1": ""
+
+  # Enhanced rendering options
   kubernetesVersion: 1.31
+  markdownDisabled: false
+  frontMatter:
+    title: "API Reference"
+    description: "Complete API reference for LlamaStack Kubernetes Operator"
+    weight: 100
+
+  # Custom sections
+  sections:
+    - title: "Overview"
+      content: |
+        This document contains the API reference for the LlamaStack Kubernetes Operator.
+        The operator manages LlamaStack distributions in Kubernetes clusters.
+
+        ## Quick Links
+
+        - [LlamaStackDistribution](#llamastackdistribution) - Main resource for deploying LlamaStack
+        - [Getting Started Guide](../getting-started/quick-start/) - Quick start tutorial
+        - [Examples](../examples/) - Real-world configuration examples
+
+    - title: "Resource Types"
+      content: |
+        The LlamaStack Operator defines the following Kubernetes custom resources: