Add auto-generated template schema documentation

README.md

@@ -138,6 +138,51 @@ These directories may have sub-directories depending on their size and grouped s
 - `notebooks` — This is where notebooks retrieved from the [`validmind-library` repo](https://github.com/validmind/validmind-library) live.
 - `tests` — This is where test descriptions generated from the Python source in the [`validmind-library` repo](https://github.com/validmind/validmind-library) live.
 
+### Generated documentation
+
+Some documentation content is auto-generated from backend source files. These scripts ensure the docs stay in sync with the codebase.
+
+#### Permissions documentation
+
+The permissions tables in `site/guide/configuration/manage-permissions.qmd` are auto-generated from the backend source files. To regenerate:
+
+```bash
+python scripts/generate_permissions_docs.py
+```
+
+**Requirements:**
+- The `backend` repo must be cloned at `../backend/` relative to this repo
+- Python 3.9+
+
+The script reads from:
+- `backend/src/backend/templates/platform_resources/data.json` — resource and action definitions
+- `backend/src/backend/templates/platform_resources/org_initials.json` — role permission assignments
+
+Output: `site/guide/configuration/_permissions-generated.qmd`
+
+Run this script when backend permission definitions change to keep documentation in sync.
+
+#### Template schema documentation
+
+The template schema reference in `site/guide/templates/customize-document-templates.qmd` is auto-generated from the backend JSON Schema. To regenerate:
+
+```bash
+pip install json-schema-for-humans
+python scripts/generate_template_schema_docs.py
+```
+
+**Requirements:**
+- The `backend` repo must be cloned at `../backend/` relative to this repo
+- Python 3.9+
+- `json-schema-for-humans` package installed
+
+The script reads from:
+- `backend/src/backend/templates/documentation/model_documentation/mdd_template_schema_v5.json` — template schema definition
+
+Output: `site/guide/templates/_template-schema-generated.html`
+
+Run this script when the backend template schema changes to keep documentation in sync.
+
 #### Stylesheet organization (IN PROGRESS)
 
 The site uses a modular stylesheet architecture to maintain organized and maintainable styles:

scripts/generate_template_schema_docs.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
+# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
+"""
+Generate template schema documentation from backend JSON Schema.
+
+Uses json-schema-for-humans to generate HTML documentation from the
+template schema used to validate YAML documentation templates.
+
+Usage:
+    pip install json-schema-for-humans
+    python scripts/generate_template_schema_docs.py
+
+Requirements:
+    - Backend repo must be cloned at ../backend/ relative to this repo
+    - json-schema-for-humans package installed
+"""
+import subprocess
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).parent
+REPO_ROOT = SCRIPT_DIR.parent
+BACKEND_ROOT = REPO_ROOT.parent / "backend"
+
+SCHEMA_FILE = BACKEND_ROOT / "src/backend/templates/documentation/model_documentation/mdd_template_schema_v5.json"
+OUTPUT_FILE = REPO_ROOT / "site/guide/templates/_template-schema-generated.html"
+
+# CSS overrides to fix conflicts with Quarto's Bootstrap
+CSS_OVERRIDES = """
+<!-- CSS overrides for Quarto compatibility -->
+<style>
+.breadcrumb {
+  background-color: white;
+  padding: 0px;
+}
+
+.accordion > .card .card-header {
+  margin-bottom: -1px;
+  background-color: #f7f7f7;
+}
+
+.card-body {
+  -ms-flex: 1 1 auto;
+  flex: 1 1 auto;
+  padding: 1.25rem
+}
+
+.pl-5,
+.px-5 {
+  padding-left: 3rem !important
+}
+
+.badge {
+  display: inline-block;
+  padding: .25em .4em;
+  font-size: 75%;
+  font-weight: 700;
+  line-height: 1;
+  text-align: center;
+  white-space: nowrap;
+  vertical-align: baseline;
+  border-radius: .25rem;
+  transition: color .15s ease-in-out, background-color .15s ease-in-out, border-color .15s ease-in-out, box-shadow .15s ease-in-out
+}
+
+.badge-warning {
+  color: #ffffff;
+  background-color: #de257e;
+}
+
+.badge.badge-dark {
+  color: #ffffff;
+  background-color: #083E44;
+}
+
+.btn.btn-link {
+  font-size: 18px;
+  user-select: text;
+  text-decoration: none;
+  color: #de257e;
+}
+
+.btn.btn-link:hover {
+  color: #083E44;
+}
+
+a {
+  color: #de257e;
+  text-decoration: none;
+}
+
+a:hover {
+  color: #DE257E;
+  text-decoration: underline 2px solid #083E44;
+}
+</style>
+<!-- End CSS overrides -->
+"""
+
+
+def main():
+    # Verify schema file exists
+    if not SCHEMA_FILE.exists():
+        print(f"Error: Schema file not found: {SCHEMA_FILE}")
+        print("Make sure the backend repo is cloned at ../backend/")
+        sys.exit(1)
+
+    # Check if json-schema-for-humans is installed
+    try:
+        subprocess.run(
+            ["generate-schema-doc", "--help"],
+            capture_output=True,
+            check=True
+        )
+    except FileNotFoundError:
+        print("Error: json-schema-for-humans not installed")
+        print("Install with: pip install json-schema-for-humans")
+        sys.exit(1)
+
+    # Generate HTML documentation
+    print(f"Generating schema documentation from {SCHEMA_FILE}...")
+
+    # Create temporary output
+    temp_output = OUTPUT_FILE.with_suffix(".tmp.html")
+
+    subprocess.run([
+        "generate-schema-doc",
+        "--config", "expand_buttons=true",
+        str(SCHEMA_FILE),
+        str(temp_output)
+    ], check=True)
+
+    # Read generated HTML and inject CSS overrides
+    with open(temp_output, "r") as f:
+        html_content = f.read()
+
+    # Insert CSS overrides after the opening <head> tag
+    if "<head>" in html_content:
+        html_content = html_content.replace(
+            "<head>",
+            f"<head>\n{CSS_OVERRIDES}"
+        )
+
+    # Add copyright header as HTML comment at the top
+    copyright_header = """<!-- Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+Refer to the LICENSE file in the root of this repository for details.
+SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
+
+This file is auto-generated by scripts/generate_template_schema_docs.py
+Do not edit directly. Re-run the script to update.
+
+Source: backend/src/backend/templates/documentation/model_documentation/mdd_template_schema_v5.json
+-->
+"""
+    html_content = copyright_header + html_content
+
+    # Also add Quarto styles link for proper rendering
+    html_content = html_content.replace(
+        CSS_OVERRIDES,
+        f'<link href="/styles.css" rel="stylesheet" id="quarto-bootstrap" data-mode="light">\n{CSS_OVERRIDES}'
+    )
+
+    # Write final output
+    OUTPUT_FILE.parent.mkdir(parents=True, exist_ok=True)
+    with open(OUTPUT_FILE, "w") as f:
+        f.write(html_content)
+
+    # Clean up temp file
+    temp_output.unlink()
+
+    print(f"Generated {OUTPUT_FILE}")
+
+
+if __name__ == "__main__":
+    main()