added documentation validation workflow

Author: kovtcharov

.github/workflows/claude.yml

@@ -742,8 +742,8 @@ jobs:
 
           echo "✅ Both release notes files exist"
 
-          # Validate MDX structure
-          python util/validate_mdx.py "docs/releases/$TAG_NAME.mdx" --tag "$TAG_NAME"
+          # Validate MDX structure (release notes specific)
+          python util/validate_mdx.py "docs/releases/$TAG_NAME.mdx" --tag "$TAG_NAME" --release-notes
 
       - name: Update docs.json with new release
         env:

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+name: Docs Validation
+
+on:
+  push:
+    paths:
+      - 'docs/**'
+      - 'util/validate_mdx.py'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'util/validate_mdx.py'
+      - '.github/workflows/docs.yml'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Validate MDX frontmatter
+        run: |
+          echo "Validating MDX frontmatter..."
+          find docs -name "*.mdx" | xargs python util/validate_mdx.py
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Mintlify CLI
+        run: npm install -g mintlify
+
+      - name: Validate docs with Mintlify
+        working-directory: docs
+        run: |
+          echo "Validating documentation with Mintlify..."
+          mintlify build
+          echo "✅ Documentation validated successfully"

util/validate_mdx.py

@@ -13,13 +13,16 @@
 sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")
 
 
-def validate_mdx(file_path: str, tag: str | None = None) -> list[str]:
+def validate_mdx(
+    file_path: str, tag: str | None = None, release_notes: bool = False
+) -> list[str]:
     """
-    Validate an MDX release notes file.
+    Validate an MDX file.
 
     Args:
         file_path: Path to the MDX file
         tag: Optional release tag to validate against (e.g., 'v0.16.0')
+        release_notes: If True, validate release notes specific requirements
 
     Returns:
         List of validation errors (empty if valid)
@@ -49,46 +52,56 @@ def validate_mdx(file_path: str, tag: str | None = None) -> list[str]:
             if "description:" not in frontmatter:
                 errors.append("Missing 'description' in frontmatter")
 
-            # Check title matches tag if provided
-            if tag:
+            # Check title matches tag if provided (release notes only)
+            if tag and release_notes:
                 title_match = re.search(
                     r'title:\s*["\']?([^"\'\n]+)["\']?', frontmatter
                 )
                 if title_match and tag not in title_match.group(1):
                     errors.append(f"Title should contain '{tag}'")
 
-    # Check for required sections
-    required_sections = ["## Overview", "## What's New", "## Full Changelog"]
-    for section in required_sections:
-        if section not in content:
-            errors.append(f"Missing required section: {section}")
+    # Release notes specific checks
+    if release_notes:
+        required_sections = ["## Overview", "## What's New", "## Full Changelog"]
+        for section in required_sections:
+            if section not in content:
+                errors.append(f"Missing required section: {section}")
 
-    # Check for changelog link
-    if "github.com/amd/gaia/compare/" not in content:
-        errors.append("Missing changelog comparison link")
+        if "github.com/amd/gaia/compare/" not in content:
+            errors.append("Missing changelog comparison link")
 
     return errors
 
 
 def main():
-    parser = argparse.ArgumentParser(description="Validate MDX release notes files")
-    parser.add_argument("file", help="Path to the MDX file to validate")
+    parser = argparse.ArgumentParser(description="Validate MDX files")
+    parser.add_argument("file", nargs="+", help="Path(s) to MDX file(s) to validate")
     parser.add_argument(
         "--tag", "-t", help="Release tag to validate against (e.g., v0.16.0)"
     )
+    parser.add_argument(
+        "--release-notes",
+        "-r",
+        action="store_true",
+        help="Enable release notes specific validation",
+    )
     args = parser.parse_args()
 
-    print(f"Validating {args.file}...")
-
-    errors = validate_mdx(args.file, args.tag)
-
-    if errors:
-        print("❌ Validation errors:")
-        for error in errors:
-            print(f"   - {error}")
+    all_errors = {}
+    for file_path in args.file:
+        print(f"Validating {file_path}...")
+        errors = validate_mdx(file_path, args.tag, args.release_notes)
+        if errors:
+            all_errors[file_path] = errors
+
+    if all_errors:
+        for file_path, errors in all_errors.items():
+            print(f"❌ {file_path}:")
+            for error in errors:
+                print(f"   - {error}")
         sys.exit(1)
 
-    print("✅ MDX validation passed")
+    print(f"✅ {len(args.file)} file(s) validated successfully")
     sys.exit(0)