generate-api-docs.sh

#!/usr/bin/env bash
set -euo pipefail

# Generate API documentation from windmill-react-sdk type definitions.
# Reads types from windmill-components (nested in the SDK) and
# outputs a markdown API reference.

SDK="node_modules/@windmill-labs/windmill-react-sdk"
# windmill-components may be nested inside the SDK or hoisted to top-level node_modules
WC="$SDK/node_modules/windmill-components/package"
if [ ! -d "$WC" ]; then
  WC="node_modules/windmill-components/package"
fi
CUSTOM_UI="$WC/components/custom_ui.d.ts"

if [ ! -f "$CUSTOM_UI" ]; then
  echo "ERROR: SDK types not found. Run 'npm install' first."
  exit 1
fi

python3 - "$CUSTOM_UI" <<'PYEOF'
import sys, re

custom_ui_path = sys.argv[1]

with open(custom_ui_path) as f:
    custom_ui_src = f.read()

out = []
out.append("## API Reference")
out.append("")
out.append("*Auto-generated by `generate-api-docs.sh` from SDK type definitions.*")
out.append("")

# --- Components ---
out.append("### Components")
out.append("")

components = [
    ("FlowBuilder", [
        ("mode", '{ type: "create"; path: string } | { type: "edit"; path: string } | { type: "fork"; path: string; forkPath: string }', True),
        ("onDeploy", "(path: string) => void", True),
        ("onDetails", "(path: string) => void", True),
        ("onSaveDraft", '(path: string, status: "new" | "pathChange" | undefined) => void', True),
        ("onDraftSaved", "(path: string) => void", False),
        ("onDraftError", "(error: Error) => void", False),
        ("onDeployError", "(error: Error) => void", False),
        ("customUi", "FlowBuilderWhitelabelCustomUi", False),
        ("disableAi", "boolean", False),
        ("disableFlowInputs", "boolean", False),
        ("setDraftCb", "(cb: () => void) => void", False),
    ]),
    ("ScriptBuilder", [
        ("mode", '{ type: "create"; path: string; lang: ScriptLang; summary?: string; description?: string; timeout?: number } | { type: "edit"; path: string } | { type: "fork"; path: string; forkPath: string }', True),
        ("onDeploy", "(path: string) => void", True),
        ("onDetails", "(path: string) => void", True),
        ("onSaveInitial", "(path: string) => void", True),
        ("onSaveDraft", "(path: string) => void", False),
        ("onDraftError", "(error: Error) => void", False),
        ("onDeployError", "(error: Error) => void", False),
        ("customUi", "ScriptBuilderWhitelabelCustomUi", False),
        ("neverShowMeta", "boolean", False),
    ]),
    ("ScriptEditor", [
        ("path", "string", True),
        ("code", "string", True),
        ("lang", "ScriptLang", True),
        ("tag", "string", False),
        ("onChange", "(code: string, schema: string) => void", False),
    ]),
    ("SchemaEditor", [
        ("schema", "object", True),
        ("onChange", "(schema: object) => void", False),
        ("customUi", "{ noAddPopover?: boolean }", False),
    ]),
    ("ResourceEditor", [
        ("newResource", "boolean", True),
        ("resource_type", "string", True),
        ("path", "string", False),
        ("hidePath", "boolean", False),
        ("onChange", "(e: { path: string, args: any, description: string }) => void", True),
    ]),
    ("FlowViewer", [
        ("flow", "{ summary: string; description?: string; value: FlowValue; schema?: any }", True),
    ]),
    ("FlowStatusViewer", [
        ("jobId", "string", True),
        ("workspaceId", "string", False),
        ("hideFlowResult", "boolean", False),
        ("hideDownloadInGraph", "boolean", False),
        ("hideNodeDefinition", "boolean", False),
        ("hideTimeline", "boolean", False),
        ("hideJobId", "boolean", False),
        ("hideDownloadLogs", "boolean", False),
    ]),
    ("FlowHistory", [
        ("path", "string", True),
        ("onHistoryRestore", "() => void", False),
    ]),
]

for name, props in components:
    out.append(f"#### `<{name} />`")
    out.append("")
    out.append("| Prop | Type | Required |")
    out.append("|------|------|----------|")
    for prop_name, prop_type, required in props:
        clean_type = prop_type.replace("|", "\\|")
        out.append(f"| `{prop_name}` | `{clean_type}` | {'Yes' if required else 'No'} |")
    out.append("")

# --- Utilities ---
out.append("### Utilities")
out.append("")
out.append("| Export | Description |")
out.append("|--------|-------------|")
out.append("| `switchWorkspace(workspace: string)` | Switch the active workspace context |")
out.append("| `OpenAPI` | OpenAPI configuration object (set `OpenAPI.BASE` to your Windmill API URL) |")
out.append("| `INITIAL_CODE` | Default code templates per language |")
out.append("| `customIcon` | Custom icon URLs (`{ normal: string, white: string }`) |")
out.append("")

# --- ScriptLang ---
out.append("### `ScriptLang`")
out.append("")
out.append("```typescript")
out.append("type ScriptLang =")
out.append("  | 'python3' | 'deno' | 'go' | 'bash' | 'powershell'")
out.append("  | 'postgresql' | 'mysql' | 'bigquery' | 'snowflake' | 'mssql'")
out.append("  | 'oracledb' | 'graphql' | 'nativets' | 'bun' | 'php'")
out.append("  | 'rust' | 'ansible' | 'csharp' | 'nu' | 'java' | 'ruby'")
out.append("  | 'duckdb' | 'bunnative';")
out.append("```")
out.append("")

# --- customUi types (auto-extracted) ---
out.append("### `customUi` Types")
out.append("")
out.append("These types control which UI elements are shown. All boolean fields default to `true` (visible).")
out.append("Set a field to `false` to hide the corresponding UI element.")
out.append("")

type_blocks = re.split(r'(?=export type )', custom_ui_src)
for block in type_blocks:
    block = block.strip()
    if not block.startswith("export type"):
        continue

    name_match = re.match(r'export type (\w+)\s*=\s*\{', block)
    if not name_match:
        continue

    type_name = name_match.group(1)
    out.append(f"#### `{type_name}`")
    out.append("")
    out.append("```typescript")
    clean = block.replace("export ", "")
    out.append(clean)
    out.append("```")
    out.append("")

print("\n".join(out))
PYEOF