Split API reference into separate TypeDoc manuals (#32)

* Removed git submodules and switched to direct repository cloning

* Remove repos directory from git tracking and add to .gitignore

* Update page styles for root page

* Improve header nav bar

* Update deployment action

* Update README

* Update README

* Update README

* Remove unused files

Author: willeastcott

.github/workflows/deploy.yml

@@ -1,9 +1,13 @@
-name: "typedoc"
+name: "Build and Deploy API Reference"
 
 on:
   workflow_dispatch:
   push:
     branches: [main]
+    paths-ignore:
+      - "README.md"
+      - "LICENSE"
+      - ".gitignore"
 
 permissions:
   contents: read
@@ -14,25 +18,36 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
-          submodules: true
-      - uses: actions/setup-node@v4
-      - run: npm ci
-      # Generate your TypeDoc documentation
-      - run: npm run build
-      # https://github.com/actions/upload-pages-artifact
-      - uses: actions/upload-pages-artifact@v3
+          node-version: '18'
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Build API Reference
+        run: npm run build
+        
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
         with:
-          path: ./docs  # This should be your TypeDoc "out" path.
+          path: ./docs
+  
   deploy:
-    runs-on: ubuntu-latest
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
     needs: build
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        # https://github.com/actions/deploy-pages
         uses: actions/deploy-pages@v4

.gitignore

@@ -1,3 +1,4 @@
 docs/
 node_modules/
-.npmrc
+.npmrc
+repos/

.gitmodules

@@ -1,48 +1,88 @@
 # PlayCanvas API Reference
 
-This repository builds the [PlayCanvas API Reference](https://api.playcanvas.com/). It is built using [TypeDoc](https://typedoc.org/).
+This repository builds the combined PlayCanvas API Reference. The API reference is a collection of documentation from multiple PlayCanvas repositories.
 
-## Installation
+## Requirements
 
 Ensure you have Node.js 18+ installed.
 
-After cloning the repo, initialize the submodules:
+## Configuration
 
-    git submodule init
-    git submodule update --remote
+Repository configuration is stored in `repos-config.json`. This file defines the repositories to be cloned, their URLs, and default branches:
 
-Then install all NPM dependencies:
+```json
+{
+  "repositories": [
+    {
+      "name": "engine",
+      "url": "https://github.com/playcanvas/engine.git",
+      "branch": "main"
+    },
+    ...
+  ]
+}
+```
 
-    npm install
+You can modify this file to change default branches, add new repositories, or remove existing ones.
 
-## Building
+## Building the API Reference
 
-To build the API reference manual locally, run:
+To build the combined API reference, run:
 
-    npm run build
+```bash
+npm run build
+```
 
-The manual will be output to the `docs` folder.
+This cross-platform script will:
 
-## Viewing
+1. Load the repository configuration from `repos-config.json`
+2. Clone the configured PlayCanvas repositories
+3. Install dependencies for each repository
+4. Build the TypeDoc documentation for each repository
+5. Copy the documentation to a central `docs` folder
+6. Create a main index.html file that allows navigation between the different API references
 
-To view the build manual, run:
+> [!NOTE]  
+> The build script automatically cleans and recreates the `repos` directory each time it's run, ensuring you always get a fresh build with the latest code from the configured branches.
 
-    npm run serve
+### Specifying Repository Branches
 
-Then point your browser at `http://localhost:3000`.
+The default branches for all repositories are defined in the `repos-config.json` file. This is the recommended place to set your branch configurations:
+
+```json
+{
+  "repositories": [
+    {
+      "name": "engine",
+      "url": "https://github.com/playcanvas/engine.git",
+      "branch": "release-2.6"
+    },
+    // ... other repositories
+  ]
+}
+```
+
+For temporary changes without modifying the configuration file, you can override branches using command-line arguments in the format `repo=branch`:
+
+```bash
+# Override the engine branch for a single build
+npm run build engine=dev
 
-## Updating Submodules
+# Override multiple repositories for a single build
+npm run build engine=dev pcui=feature/new-components
+```
 
-To update any of the submodules to latest commit of the `main` branch, do:
+The repository names used in the command line must match the `name` fields in the `repos-config.json` file.
 
-    cd submodules
-    cd engine (or pcui, pcui-graph, etc)
-    git pull origin main
-    cd ..
-    cd ..
-    git add submodules
-    git commit -m "Updated submodule X to latest"
-    git push
+## Viewing
+
+To view the built API reference, run:
+
+```bash
+npm run serve
+```
+
+Then point your browser at `http://localhost:3000`.
 
 ## Deployment
 

README.md

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Load repository configuration from JSON file
+let REPOS = [];
+try {
+  const configPath = path.join(__dirname, 'repos-config.json');
+  const configData = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  REPOS = configData.repositories;
+  console.log(`Loaded ${REPOS.length} repositories from configuration file`);
+} catch (error) {
+  console.error(`Error loading repository configuration: ${error.message}`);
+  process.exit(1);
+}
+
+/**
+ * Parse command line arguments to override repository branches
+ */
+function parseBranchArgs() {
+  const args = process.argv.slice(2);
+  
+  // Process arguments in the format: repo=branch (e.g., engine=dev)
+  for (const arg of args) {
+    const match = arg.match(/^([^=]+)=(.+)$/);
+    if (match) {
+      const [, repoName, branchName] = match;
+      const repo = REPOS.find(r => r.name === repoName);
+      
+      if (repo) {
+        console.log(`Setting custom branch for ${repoName}: ${branchName}`);
+        repo.branch = branchName;
+      } else {
+        console.warn(`Warning: Unknown repository '${repoName}' specified in arguments`);
+      }
+    }
+  }
+}
+
+/**
+ * Execute shell command and display the output
+ */
+function runCommand(command, options = {}) {
+  console.log(`Running: ${command}`);
+  return execSync(command, { stdio: 'inherit', ...options });
+}
+
+/**
+ * Delete directory if it exists
+ */
+function deleteDir(dir) {
+  if (fs.existsSync(dir)) {
+    console.log(`Removing existing directory: ${dir}`);
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Create directory if it doesn't exist
+ */
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    console.log(`Creating directory: ${dir}`);
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Copy directory contents recursively
+ */
+function copyDirContents(src, dest) {
+  if (!fs.existsSync(src)) {
+    console.log(`Source directory doesn't exist: ${src}`);
+    return;
+  }
+
+  ensureDir(dest);
+  
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    
+    if (entry.isDirectory()) {
+      copyDirContents(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Main function to build the documentation
+ */
+async function buildDocs() {
+  try {
+    // Parse command line arguments for branch overrides
+    parseBranchArgs();
+    
+    // Create docs directory if it doesn't exist
+    ensureDir('docs');
+    
+    // Remove existing repos directory and create a new one
+    deleteDir('repos');
+    ensureDir('repos');
+    
+    // Process each repository
+    for (const repo of REPOS) {
+      console.log(`\n========== Processing ${repo.name} (branch: ${repo.branch}) ==========`);
+      
+      // Change to repos directory
+      process.chdir(path.join(process.cwd(), 'repos'));
+      
+      // Clone the repository with specified branch
+      runCommand(`git clone -b ${repo.branch} ${repo.url} ${repo.name}`);
+      
+      // Change to repository directory
+      process.chdir(path.join(process.cwd(), repo.name));
+      
+      // Install dependencies
+      runCommand('npm install');
+      
+      // Build documentation
+      runCommand('npm run docs');
+      
+      // Copy docs to the main docs directory if they exist
+      const docsDir = path.join(process.cwd(), 'docs');
+      if (fs.existsSync(docsDir)) {
+        const targetDir = path.join(process.cwd(), '..', '..', 'docs', repo.name);
+        console.log(`Copying docs from ${docsDir} to ${targetDir}`);
+        ensureDir(targetDir);
+        copyDirContents(docsDir, targetDir);
+      }
+      
+      // Return to root directory
+      process.chdir(path.join(process.cwd(), '..', '..'));
+      
+      console.log(`Completed processing ${repo.name}`);
+    }
+    
+    // Copy the index.html to the docs directory
+    console.log('\nCopying index.html file...');
+    const sourceIndexPath = path.join(__dirname, 'index.html');
+    if (!fs.existsSync(sourceIndexPath)) {
+      throw new Error(`Source index.html not found: ${sourceIndexPath}`);
+    }
+    fs.copyFileSync(sourceIndexPath, path.join('docs', 'index.html'));
+    
+    // Copy favicon
+    console.log('Copying favicon...');
+    fs.copyFileSync('favicon.ico', path.join('docs', 'favicon.ico'));
+    
+    // Copy assets directory if it exists
+    if (fs.existsSync('assets')) {
+      console.log('Copying assets directory...');
+      ensureDir(path.join('docs', 'assets'));
+      copyDirContents('assets', path.join('docs', 'assets'));
+    }
+    
+    console.log('\nDocumentation build complete. Run "npm run serve" to view it.');
+  } catch (error) {
+    console.error(`\nError: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// Run the build process
+buildDocs();