Adding docs build (#16)

Mermaid js

cleanup

links

Signed-off-by: Aidan Reilly <aireilly@redhat.com>

Author: aireilly

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Build docs
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v5
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: pip install zensical
+      - name: Copy README to docs with fixed relative links
+        run: |
+          python3 -c "
+          import re, os
+          repo_url = os.environ['REPO_URL']
+          with open('README.md') as f:
+              content = f.read()
+          # Strip ./docs/ prefix so links resolve within the docs directory
+          content = content.replace('./docs/', './')
+          # Convert remaining relative links with directory paths to absolute GitHub URLs
+          # (these point to repo files outside docs/, e.g. ./validation/README.md)
+          content = re.sub(
+              r'(\[[^\]]*\])\(\./([^)]*\/[^)]*)\)',
+              rf'\1({repo_url}/blob/main/\2)',
+              content,
+          )
+          with open('docs/index.md', 'w') as f:
+              f.write(content)
+          "
+        env:
+          REPO_URL: ${{ github.server_url }}/${{ github.repository }}
+      - run: zensical build --clean
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

.github/workflows/link-check.yaml

@@ -0,0 +1,27 @@
+name: Check links
+
+on:
+  pull_request:
+    paths:
+      - '**/*.md'
+      - '.lychee.toml'
+      - '.github/workflows/link-check.yaml'
+
+permissions:
+  contents: read
+
+jobs:
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: lycheeverse/lychee-action@v2
+        with:
+          args: >
+            --no-progress
+            --exclude '^https?://localhost'
+            '**/*.md'
+          fail: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,2 @@
+.claude/
+site/

.lychee.toml

@@ -0,0 +1,14 @@
+# https://lychee.cli.rs/usage/config/
+include_mail = false
+max_concurrency = 16
+max_retries = 3
+user_agent = "Mozilla/5.0 (compatible; lychee/0.18; +https://github.com/lycheeverse/lychee)"
+timeout = 30
+accept = [200, 203, 429]
+include_fragments = false
+include_verbatim = true
+exclude = [
+  "^https?://[0-9]+\\.xx\\.",
+  "^hf://",
+  "^registry\\.redhat\\.io",
+]

README.md

@@ -1,4 +1,4 @@
-# rhaii-on-xks
+# Red Hat AI Inference on managed Kubernetes
 
 Infrastructure Helm charts for deploying Red Hat AI Inference Server (KServe LLMInferenceService) on managed Kubernetes platforms (AKS, CoreWeave).
 

charts/cert-manager-operator/README.md

@@ -148,7 +148,7 @@ The update-bundle.sh script:
 Personal Red Hat pull secrets and tokens typically expire (yearly). Registry
 Service Accounts created via the [Red Hat terms-based registry](https://access.redhat.com/terms-based-registry/)
 do not expire and are recommended for production (see Section 1.3 of the
-[deployment guide](../docs/deploying-llm-d-on-managed-kubernetes.md)).
+[deployment guide](../../docs/deploying-llm-d-on-managed-kubernetes.md)).
 
 To update expiring credentials:
 

docs/deploying-llm-d-on-managed-kubernetes.md

@@ -165,18 +165,16 @@ Red Hat AI Inference Server on managed Kubernetes consists of the following comp
 
 ### Component Interaction
 
-```text
-                                    ┌─────────────────────────────────────┐
-                                    │         Kubernetes Cluster          │
-┌──────────┐    ┌──────────────┐    │  ┌─────────┐    ┌────────────────┐  │
-│  Client  │───▶│   Gateway    │───▶│  │   EPP   │───▶│  vLLM Pods     │  │
-│          │    │   (Istio)    │    │  │Scheduler│    │  (Model)       │  │
-└──────────┘    └──────────────┘    │  └─────────┘    └────────────────┘  │
-                                    │        ▲               ▲            │
-                                    │        │    mTLS      │            │
-                                    │        └───────────────┘            │
-                                    │              cert-manager           │
-                                    └─────────────────────────────────────┘
+```mermaid
+graph LR
+    Client --> Gateway["Gateway<br/>(Istio)"]
+
+    subgraph Kubernetes Cluster
+        Gateway --> EPP["EPP<br/>Scheduler"]
+        EPP --> vLLM["vLLM Pods<br/>(Model)"]
+        cm["cert-manager"] -. mTLS .-> EPP
+        cm["cert-manager"] -. mTLS .-> vLLM
+    end
 ```
 
 ---
@@ -606,7 +604,8 @@ make deploy-kserve
 For assistance with Red Hat AI Inference Server deployments, contact Red Hat Support or consult the product documentation.
 
 **Additional Resources:**
-- [KServe Chart README](https://github.com/opendatahub-io/rhaii-on-xks/blob/main/charts/kserve/README.md) - KServe Helm chart details, PKI prerequisites, and OCI registry install
-- [Preflight Validation](https://github.com/opendatahub-io/rhaii-on-xks/blob/main/validation/README.md) - Cluster readiness and post-deployment validation checks
-- [Monitoring Setup Guide](../monitoring-stack/) - Optional Prometheus/Grafana configuration for dashboards and autoscaling
-- [KServe LLMInferenceService Samples](https://github.com/red-hat-data-services/kserve/tree/rhoai-3.4/docs/samples/llmisvc)
+
+* [KServe Chart README](https://github.com/opendatahub-io/rhaii-on-xks/blob/main/charts/kserve/README.md) - KServe Helm chart details, PKI prerequisites, and OCI registry install
+* [Preflight Validation](https://github.com/opendatahub-io/rhaii-on-xks/blob/main/validation/README.md) - Cluster readiness and post-deployment validation checks
+* [Monitoring Setup Guide](../monitoring-stack/) - Optional Prometheus/Grafana configuration for dashboards and autoscaling
+* [KServe LLMInferenceService Samples](https://github.com/red-hat-data-services/kserve/tree/rhoai-3.4/docs/samples/llmisvc)

docs/images/odh.png

@@ -52,4 +52,4 @@ kubectl port-forward -n monitoring svc/prometheus-operated 9090:9090
 ## Dashboards
 
 Community dashboards available at:
-- [llm-d Dashboards](https://github.com/llm-d/llm-d/tree/main/docs/monitoring/dashboards)
+- [llm-d Dashboards](https://github.com/llm-d/llm-d/tree/main/docs/monitoring/grafana/dashboards)

monitoring-stack/README.md

@@ -0,0 +1,44 @@
+[project]
+site_name = "Red Hat AI Inference on managed Kubernetes"
+site_url = "https://opendatahub-io.github.io/rhaii-on-xks"
+repo_url = "https://github.com/opendatahub-io/rhaii-on-xks"
+edit_uri = "edit/main/docs/"
+nav = [
+    {"Home" = [
+    {"Get started" = "index.md"},
+    {"Architecture" = "architecture-xks-deployment.md"},
+    ]},
+    {"Deploy" = [
+        {"Deploy" = "deploying-llm-d-on-managed-kubernetes.md"},
+        {"Set up the gateway" = "gateway-setup-for-kserve.md"},
+        {"Debug" = "collecting-debug-information.md"},
+    ]},
+]
+
+[project.theme]
+logo = "images/odh.png"
+features = [
+    "navigation.tabs",
+    "navigation.tabs.sticky",
+    "navigation.sections",
+    "navigation.expand",
+    "content.action.edit",
+    "content.action.view",
+]
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme: light)"
+scheme = "default"
+toggle.icon = "lucide/sun"
+toggle.name = "Switch to dark mode"
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme: dark)"
+scheme = "slate"
+toggle.icon = "lucide/moon"
+toggle.name = "Switch to light mode"
+
+[project.markdown_extensions.pymdownx.superfences]
+custom_fences = [
+  { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" }
+]