Website

.gitignore

@@ -35,3 +35,8 @@ __pycache__/
 
 # Kubeconfig might contain secrets
 *.kubeconfig
+
+# MkDocs generated site
+site/
+site-src/reference/index.md
+.venv-mkdocs/

Makefile

@@ -150,6 +150,27 @@ build-installer: manifests generate kustomize ## Generate a consolidated YAML wi
 	cd config/manager && "$(KUSTOMIZE)" edit set image controller=${IMG}
 	"$(KUSTOMIZE)" build config/default > dist/install.yaml
 
+##@ Documentation
+
+.PHONY: api-ref-docs
+api-ref-docs: ## Generate API reference documentation
+	./hack/mkdocs/generate.sh
+
+.PHONY: build-docs
+build-docs: api-ref-docs ## Build documentation site using Docker
+	$(CONTAINER_TOOL) build -t mkdocs-builder -f hack/mkdocs/image/Dockerfile hack/mkdocs/image
+	$(CONTAINER_TOOL) run --rm -v $(shell pwd):/work -w /work mkdocs-builder build
+
+.PHONY: build-docs-netlify
+build-docs-netlify: api-ref-docs ## Build documentation site for Netlify deployment
+	pip install -r hack/mkdocs/image/requirements.txt
+	python -m mkdocs build
+
+.PHONY: live-docs
+live-docs: api-ref-docs ## Run live documentation server using Docker
+	$(CONTAINER_TOOL) build -t mkdocs-builder -f hack/mkdocs/image/Dockerfile hack/mkdocs/image
+	$(CONTAINER_TOOL) run --rm -it -v $(shell pwd):/work -w /work -p 3000:3000 mkdocs-builder serve --dev-addr=0.0.0.0:3000
+
 ##@ Deployment
 
 ifndef ignore-not-found

README.md

@@ -196,6 +196,8 @@ make test
 
 ## Community, discussion, contribution, and support
 
+This project is part of Kubernetes [SIG Apps](https://github.com/kubernetes/community/blob/main/sig-apps/README.md).
+
 Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
 
 You can reach the maintainers of this project at:

crd-ref-docs.yaml

@@ -0,0 +1,19 @@
+processor:
+  # Ignore fields using regex patterns (RE2 syntax)
+  ignoreFields:
+    - "TypeMeta$"
+    - "ObjectMeta$"
+    - "ListMeta$"
+  # Ignore types matching regex patterns
+  ignoreTypes:
+    - "()List$"
+
+render:
+  kubernetesVersion: "1.28"
+
+output:
+  markdown:
+    outputFile: site-src/reference/index.md
+
+sourceDirectories:
+  - api/v1alpha1

hack/mkdocs/generate.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+
+# Copyright 2024 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.
+
+set -e
+set -u
+set -o pipefail
+
+SCRIPT_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
+
+cd "${SCRIPT_ROOT}"
+
+echo "Generating API reference documentation..."
+
+# Install crd-ref-docs if not present
+if ! command -v crd-ref-docs &> /dev/null; then
+    echo "Installing crd-ref-docs..."
+    go install github.com/elastic/crd-ref-docs@latest
+fi
+
+# Generate the API reference documentation
+crd-ref-docs \
+    --source-path=./api/v1alpha1 \
+    --config=./crd-ref-docs.yaml \
+    --renderer=markdown \
+    --output-path=./site-src/reference/index.md
+
+echo "API reference documentation generated successfully!"

hack/mkdocs/image/Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.13-alpine
+
+# Install dependencies
+COPY requirements.txt /tmp/
+RUN pip install --no-cache-dir -r /tmp/requirements.txt
+
+# Set working directory
+WORKDIR /work
+
+# Copy entrypoint script
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# Expose port for local development
+EXPOSE 3000
+
+# Set entrypoint
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["build"]

hack/mkdocs/image/entrypoint.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+
+set -e
+
+# Run mkdocs command
+if [ "$1" = "build" ]; then
+    echo "Building MkDocs site..."
+    exec python -m mkdocs build
+elif [ "$1" = "serve" ]; then
+    echo "Starting MkDocs development server..."
+    shift  # Remove 'serve' from arguments
+    exec python -m mkdocs serve "$@"
+else
+    # Run custom command
+    exec "$@"
+fi

hack/mkdocs/image/requirements.txt

@@ -0,0 +1,7 @@
+mkdocs~=1.6
+mkdocs-material~=9.5
+mkdocs-material-extensions~=1.3
+mkdocs-awesome-pages-plugin~=2.9
+mkdocs-mermaid2-plugin~=1.1
+pymdown-extensions~=10.2
+markdown~=3.6

hack/mkdocs/local-serve.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+
+# Script to run MkDocs locally using a Python virtual environment
+# This avoids conflicts with system Python on macOS
+
+set -e
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+ROOT_DIR="$( cd "${SCRIPT_DIR}/../.." && pwd )"
+VENV_DIR="${ROOT_DIR}/.venv-mkdocs"
+
+cd "${ROOT_DIR}"
+
+# Create virtual environment if it doesn't exist
+if [ ! -d "${VENV_DIR}" ]; then
+    echo "Creating Python virtual environment..."
+    python3 -m venv "${VENV_DIR}"
+fi
+
+# Activate virtual environment
+echo "Activating virtual environment..."
+source "${VENV_DIR}/bin/activate"
+
+# Install/upgrade dependencies
+echo "Installing MkDocs dependencies..."
+pip install -q --upgrade pip
+pip install -q -r hack/mkdocs/image/requirements.txt
+
+# Generate API docs
+echo "Generating API documentation..."
+make api-ref-docs
+
+# Start MkDocs server
+echo ""
+echo "Starting MkDocs development server..."
+echo "Documentation will be available at: http://127.0.0.1:3000"
+echo "Press Ctrl+C to stop"
+echo ""
+
+python -m mkdocs serve --dev-addr=127.0.0.1:3000

mkdocs.yml

@@ -0,0 +1,63 @@
+site_name: MCP Lifecycle Operator
+site_url: https://mcp-lifecycle-operator.sigs.k8s.io
+repo_url: https://github.com/kubernetes-sigs/mcp-lifecycle-operator
+repo_name: kubernetes-sigs/mcp-lifecycle-operator
+edit_uri: edit/main/site-src/
+site_dir: site
+docs_dir: site-src
+
+theme:
+  name: material
+  icon:
+    repo: fontawesome/brands/github
+  logo: images/logo.png
+  favicon: images/favicon-64.png
+  palette:
+    primary: custom
+  features:
+    - search.highlight
+    - navigation.tabs
+    - navigation.top
+    - navigation.expand
+    - content.code.copy
+    - content.action.edit
+
+plugins:
+  - search
+  - awesome-pages
+  - mermaid2
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - tables
+  - toc:
+      permalink: true
+  - attr_list
+  - md_in_html
+
+extra_css:
+  - stylesheets/extra.css
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/kubernetes-sigs/mcp-lifecycle-operator
+    - icon: fontawesome/brands/slack
+      link: https://kubernetes.slack.com/messages/sig-apps

netlify.toml

@@ -0,0 +1,11 @@
+[build]
+  publish = "site"
+  command = "make build-docs-netlify"
+
+[build.environment]
+  PYTHON_VERSION = "3.8"
+
+[[redirects]]
+  from = "/*"
+  to = "/index.html"
+  status = 200

site-src/.pages

@@ -0,0 +1,6 @@
+nav:
+  - Home: index.md
+  - Introduction: introduction.md
+  - Guides: guides
+  - Reference: reference
+  - Contributing: contributing

site-src/README.md

@@ -0,0 +1,94 @@
+# MCP Lifecycle Operator Website
+
+This directory contains the source files for the MCP Lifecycle Operator documentation website.
+
+## Directory Structure
+
+```
+site-src/
+├── index.md              # Landing page
+├── introduction.md       # Introduction and overview
+├── guides/               # Getting started guides
+│   ├── index.md
+│   └── quickstart.md
+├── reference/            # API reference documentation
+│   └── index.md         # Auto-generated from Go API types
+├── contributing/         # Contributing guide
+│   └── index.md
+├── images/               # Image assets
+└── stylesheets/          # Custom CSS
+    └── extra.css
+```
+
+## Building the Website
+
+### Prerequisites
+
+- Docker (recommended for local development)
+- Python 3.8+ with pip (for Netlify deployment)
+
+### Local Development
+
+**Option 1: Using Docker (recommended for consistency)**
+
+```bash
+make live-docs
+```
+
+This will start a development server at http://localhost:3000
+
+**Option 2: Using Python virtual environment (faster startup)**
+
+```bash
+./hack/mkdocs/local-serve.sh
+```
+
+This will start a development server at http://127.0.0.1:3000
+
+### Build for Production
+
+Build the static site:
+
+```bash
+make build-docs
+```
+
+The generated site will be in the `site/` directory.
+
+### Generate API Documentation
+
+The API reference documentation is auto-generated from Go source code:
+
+```bash
+make api-ref-docs
+```
+
+This creates `site-src/reference/index.md` from the CRD types in `api/v1alpha1/`.
+
+## Technology Stack
+
+- **Static Site Generator**: MkDocs ~1.6
+- **Theme**: Material for MkDocs ~9.7
+- **Plugins**:
+  - `awesome-pages`: Advanced navigation control
+  - `mermaid2`: Diagram support
+  - `search`: Full-text search
+
+## Deployment
+
+The website is deployed to Netlify automatically when changes are pushed to the main branch.
+
+Netlify configuration: `netlify.toml`
+
+## Making Changes
+
+1. Edit content in `site-src/`
+2. Run `make live-docs` to preview changes
+3. Commit and push to trigger deployment
+
+## Content Guidelines
+
+- Use Markdown with Material extensions
+- Include code examples where appropriate
+- Add diagrams using Mermaid syntax
+- Keep navigation structure in `.pages` files