Ref/documentation

.cursor/rules/synced-docs.mdc

@@ -0,0 +1,20 @@
+---
+description: Public prose/API doc trees are synced from PixelRoot32-Game-Engine; edit the engine then npm run sync-docs.
+globs: tools/**,examples/**,guide/**,api/**,architecture/**,philosophy/**,migration/**,scripts/sync-docs-from-engine.mjs
+---
+
+# Generated documentation
+
+Do **not** hand-edit synced trees except by running `npm run sync-docs` (or `node scripts/sync-docs-from-engine.mjs --engine <path>`) after changing sources in **PixelRoot32-Game-Engine**:
+
+| Site | Engine (`docs/` unless noted) |
+|------|-------------------------------|
+| `tools/` | `tools/` |
+| `examples/*.md` | `examples/` READMEs + `guide/entities-scene-tutorial.md` |
+| `guide/` | `guide/` (includes coding style, guidelines, platform compatibility, `performance/`) |
+| `api/` | `api/` |
+| `architecture/` | `architecture/` |
+| `philosophy/` | `philosophy/` |
+| `migration/` | `migration/` |
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) at the repo root.

.github/workflows/documentation.yml

@@ -7,27 +7,33 @@ on:
       - 'guide/**'
       - 'api/**'
       - 'architecture/**'
+      - 'philosophy/**'
+      - 'migration/**'
       - 'examples/**'
       - 'tools/**'
       - 'index.md'
       - 'home.md'
       - '.vitepress/**'
       - 'package.json'
       - 'package-lock.json'
+      - 'scripts/sync-docs-from-engine.mjs'
       - '.github/workflows/documentation.yml'
   pull_request:
     branches: [main, develop]
     paths:
       - 'guide/**'
       - 'api/**'
       - 'architecture/**'
+      - 'philosophy/**'
+      - 'migration/**'
       - 'examples/**'
       - 'tools/**'
       - 'index.md'
       - 'home.md'
       - '.vitepress/**'
       - 'package.json'
       - 'package-lock.json'
+      - 'scripts/sync-docs-from-engine.mjs'
       - '.github/workflows/documentation.yml'
 
 permissions:
@@ -48,6 +54,13 @@ jobs:
         with:
           fetch-depth: 1
 
+      - name: Checkout engine (canonical documentation source)
+        uses: actions/checkout@v4
+        with:
+          repository: PixelRoot32-Game-Engine/PixelRoot32-Game-Engine
+          path: engine
+          ref: ${{ vars.ENGINE_DOCS_REF || 'main' }}
+
       - name: Setup Pages
         uses: actions/configure-pages@v4
 
@@ -60,6 +73,12 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Sync all engine docs, verify no drift
+        run: |
+          node scripts/sync-docs-from-engine.mjs --engine ./engine
+          rm -rf ./engine
+          git diff --stat tools examples guide api architecture philosophy migration
+
       - name: Build documentation
         env:
           # Default: GitHub project pages https://<owner>.github.io/<repo>/

.gitignore

@@ -1,6 +1,6 @@
 # --- Project (PixelRoot32-Docs) ---
 # Local scripts not versioned
-scripts/
+# scripts/  # (disabled for CI sync script)
 
 # Drafts / auxiliary files with prefix _
 _*

.vitepress/buildApiGeneratedSidebar.ts

@@ -0,0 +1,65 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { DefaultTheme } from 'vitepress'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+/** Subfolders under `api/generated/` (excluding `index.md` at root). */
+const CATEGORY_ORDER = [
+  'audio',
+  'core',
+  'math',
+  'physics',
+  'graphics',
+  'input',
+  'drivers',
+  'platforms',
+  'test',
+] as const
+
+const CATEGORY_LABEL: Record<string, string> = {
+  audio: 'Audio',
+  core: 'Core',
+  math: 'Math',
+  physics: 'Physics',
+  graphics: 'Graphics',
+  input: 'Input',
+  drivers: 'Drivers',
+  platforms: 'Platforms',
+  test: 'Test',
+}
+
+/**
+ * Sidebar items for **Reference (Auto)**: index + one collapsible group per
+ * generated category (scanned from disk so new types appear after sync).
+ */
+export function buildApiGeneratedSidebarItems(): DefaultTheme.SidebarItem[] {
+  const root = path.join(__dirname, '..', 'api', 'generated')
+  const items: DefaultTheme.SidebarItem[] = [
+    { text: 'Index', link: '/api/generated/' },
+  ]
+
+  for (const cat of CATEGORY_ORDER) {
+    const dir = path.join(root, cat)
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) continue
+
+    const files = fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith('.md') && f !== 'index.md')
+      .sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }))
+
+    const subItems: DefaultTheme.SidebarItem[] = files.map((f) => {
+      const name = path.basename(f, '.md')
+      return { text: name, link: `/api/generated/${cat}/${name}` }
+    })
+
+    items.push({
+      text: CATEGORY_LABEL[cat] ?? cat,
+      collapsed: true,
+      items: subItems,
+    })
+  }
+
+  return items
+}