Update documentation for guardrails

.github/workflows/docs-guardrails.yml

@@ -0,0 +1,26 @@
+name: Documentation Docker Image
+
+on:
+  push:
+    branches: ["guardrails"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+
+      - name: Login to GitHub Container Registry
+        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
+
+      - name: Build Docs
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64
+          push: true
+          tags: ghcr.io/${{ github.repository }}/docs:guardrails

.gitignore

@@ -0,0 +1,5 @@
+__pycache__/mkdocs_config.cpython-312.pyc
+__pycache__
+visited.log
+contents.txt
+broken-links.txt

Dockerfile

@@ -12,4 +12,4 @@ RUN mkdocs build --clean
 
 # serve the documentation if DEV_MODE is set, otherwise, serve built documentation
 # for prod serving, we copy everything to root/docs/, as this is where the docs are actually served from in the container
-CMD if [ "$DEV_MODE" = "true" ]; then mkdocs serve -a 0.0.0.0:8000; else mkdocs build; mkdir -p root; mv site root/docs; cd root; python -m http.server 8000 --bind 0.0.0.0; fi
+CMD if [ "$DEV_MODE" = "true" ]; then mkdocs serve -a 0.0.0.0:8000; else mkdocs build; mkdir -p root; mv site root/docs-guardrails; cd root; python -m http.server 8000 --bind 0.0.0.0; fi

check-links.py

@@ -0,0 +1,96 @@
+import asyncio
+from playwright.async_api import async_playwright
+from urllib.parse import urljoin, urldefrag
+from collections import deque
+import aiofiles
+
+BASE_URL = "http://localhost:8000"
+LOG_FILE = "visited.log"
+BROKEN_FILE = "broken-links.txt"
+CONTENTS_FILE = "contents.txt"
+
+
+async def check_page(page, source_url):
+    url = page.url
+    html = await page.content()
+
+    # Save page content
+    async with aiofiles.open(CONTENTS_FILE, "a") as f:
+        await f.write(html)
+
+    # Check for 404
+    if "<h1>404 - Not found</h1>" in html:
+        async with aiofiles.open(BROKEN_FILE, "a") as f:
+            await f.write(f"[404] {url} (linked from {source_url})\n")
+
+    # Broken image sources
+    bad_imgs = await page.eval_on_selector_all(
+        "img[src]",
+        """els => els
+            .map(e => ({ src: e.src, complete: e.complete, naturalWidth: e.naturalWidth }))
+            .filter(e => !e.complete || e.naturalWidth === 0)
+            .map(e => e.src)""",
+    )
+    if bad_imgs:
+        async with aiofiles.open(BROKEN_FILE, "a") as f:
+            for img in bad_imgs:
+                await f.write(f"[Broken IMG] {img} on {url}\n")
+
+    # Check anchor hrefs
+    anchors = await page.eval_on_selector_all("a[href]", "els => els.map(e => e.href)")
+    for link in anchors:
+        link_url, _ = urldefrag(urljoin(url, link))
+        if not link_url.startswith(BASE_URL):
+            continue
+        try:
+            res = await page.context.request.get(link_url)
+            if res.status >= 400:
+                async with aiofiles.open(BROKEN_FILE, "a") as f:
+                    await f.write(
+                        f"[Broken LINK] {link_url} on {url} (status {res.status})\n"
+                    )
+        except Exception as e:
+            async with aiofiles.open(BROKEN_FILE, "a") as f:
+                await f.write(f"[Broken LINK] {link_url} on {url} (error {e})\n")
+
+
+async def crawl(base_url):
+    visited = set()
+    queue = deque([(base_url, "(start)")])
+
+    async with async_playwright() as p:
+        browser = await p.chromium.launch()
+        context = await browser.new_context()
+        page = await context.new_page()
+
+        async with aiofiles.open(LOG_FILE, "w") as log_file:
+            while queue:
+                raw_url, source_url = queue.popleft()
+                url, _ = urldefrag(raw_url)
+
+                if url in visited or not url.startswith(base_url):
+                    continue
+                visited.add(url)
+
+                try:
+                    await page.goto(url)
+                    await check_page(page, source_url)
+                    await log_file.write(url + "\n")
+                    await log_file.flush()
+
+                    links = await page.eval_on_selector_all(
+                        "a[href]", "els => els.map(e => e.href)"
+                    )
+                    for link in links:
+                        abs_link, _ = urldefrag(urljoin(url, link))
+                        if abs_link.startswith(base_url) and abs_link not in visited:
+                            queue.append((abs_link, url))
+
+                except Exception as e:
+                    print(f"Error visiting {url}: {e}")
+
+        await browser.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(crawl(BASE_URL))

collect-frontmatter.py

@@ -0,0 +1,41 @@
+import os
+import re
+import yaml
+from pathlib import Path
+import json
+
+FRONTMATTER_PATTERN = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+
+
+def parse_frontmatter(filepath):
+    with open(filepath, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    match = FRONTMATTER_PATTERN.match(content)
+    if not match:
+        return None
+
+    try:
+        frontmatter = yaml.safe_load(match.group(1))
+        return {
+            "title": frontmatter.get("title", ""),
+            "description": frontmatter.get("description", ""),
+        }
+    except yaml.YAMLError:
+        print(f"Failed to parse YAML in {filepath}")
+        return None
+
+
+def collect_frontmatter_data():
+    data = {}
+    docs_path = Path("./docs")
+    for md_file in docs_path.rglob("*.md"):
+        parsed = parse_frontmatter(md_file)
+        if parsed:
+            data[str(md_file)] = parsed
+    return data
+
+
+if __name__ == "__main__":
+    result = collect_frontmatter_data()
+    print(json.dumps(result, indent=2))