Feature: SDK Reference generation & hosting

.github/workflows/sdk-reference-sync.yml

@@ -0,0 +1,113 @@
+name: Sync SDK Reference Documentation
+
+on:
+  # manual trigger with inputs
+  workflow_dispatch:
+    inputs:
+      sdk:
+        description: "SDK to generate (see sdks.config.ts for available SDKs, or use 'all')"
+        required: true
+        default: "all"
+        type: string
+      version:
+        description: "Version to generate (all, latest, or specific like v2.9.0)"
+        required: true
+        default: "all"
+        type: string
+
+  # triggered from e2b-dev/e2b repo on release
+  repository_dispatch:
+    types: [sdk-release]
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout docs repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install generator dependencies
+        working-directory: sdk-reference-generator
+        run: pnpm install --frozen-lockfile
+
+      - name: Install Python dependencies
+        run: pip install -r requirements.txt
+
+      - name: Install Poetry
+        run: pip install poetry
+
+      - name: Determine SDK and Version
+        id: params
+        run: |
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            SDK="${{ github.event.inputs.sdk }}"
+            VERSION="${{ github.event.inputs.version }}"
+          elif [[ "${{ github.event_name }}" == "repository_dispatch" ]]; then
+            SDK="${{ github.event.client_payload.sdk }}"
+            # on repository_dispatch, default to "all" to auto-detect missing versions
+            VERSION="${{ github.event.client_payload.version }}"
+            VERSION="${VERSION:-all}"
+          fi
+
+          echo "sdk=${SDK:-all}" >> $GITHUB_OUTPUT
+          echo "version=${VERSION:-all}" >> $GITHUB_OUTPUT
+
+      - name: Generate SDK Reference
+        working-directory: sdk-reference-generator
+        run: |
+          pnpm run generate \
+            --sdk "${{ steps.params.outputs.sdk }}" \
+            --version "${{ steps.params.outputs.version }}"
+
+      - name: Verify generated files
+        run: |
+          echo "Generated SDK reference files:"
+          find docs/sdk-reference -type f -name "*.mdx" 2>/dev/null | head -20 || echo "No MDX files found"
+
+      - name: Commit and push changes
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          git add docs/sdk-reference/
+          git add docs.json
+
+          if git diff --staged --quiet; then
+            echo "No changes to commit"
+          else
+            git commit -m "[skip ci] Update SDK reference: ${{ steps.params.outputs.sdk }} ${{ steps.params.outputs.version }}"
+            git push
+          fi
+
+      - name: Summary
+        run: |
+          echo "## SDK Reference Generation Complete" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- **SDK**: ${{ steps.params.outputs.sdk }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Version**: ${{ steps.params.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Generated Files" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          find docs/sdk-reference -type f -name "*.mdx" | wc -l | xargs echo "Total MDX files:" >> $GITHUB_STEP_SUMMARY
+          find docs/sdk-reference -type f -name "*.mdx" >> $GITHUB_STEP_SUMMARY || true
+          echo '```' >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -1,2 +1,7 @@
 .idea
 .DS_Store
+
+node_modules
+
+# Generated SDK navigation (intermediate file)
+sdk_navigation.json

.mintignore

@@ -0,0 +1,3 @@
+sdk-reference-generator/
+
+scripts/

docs.json

@@ -168,18 +168,24 @@
           },
           {
             "group": "Deployment",
-            "pages": ["docs/byoc"]
+            "pages": [
+              "docs/byoc"
+            ]
           },
           {
             "group": "Migration",
-            "pages": ["docs/migration/v2"]
+            "pages": [
+              "docs/migration/v2"
+            ]
           },
           {
             "group": "Troubleshooting",
             "pages": [
               {
                 "group": "SDKs",
-                "pages": ["docs/troubleshooting/sdks/workers-edge-runtime"]
+                "pages": [
+                  "docs/troubleshooting/sdks/workers-edge-runtime"
+                ]
               },
               {
                 "group": "Templates",
@@ -191,11 +197,6 @@
             ]
           }
         ]
-      },
-      {
-        "anchor": "SDK Reference",
-        "icon": "brackets-curly",
-        "href": "https://e2b.dev/docs/sdk-reference"
       }
     ],
     "global": {}

requirements.txt

@@ -0,0 +1,4 @@
+# Python dependencies for SDK reference generation
+pydoc-markdown>=4.8.2
+poetry>=1.8.0
+

sdk-reference-generator/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+

sdk-reference-generator/README.md

@@ -0,0 +1,166 @@
+# SDK Reference Documentation Generator
+
+TypeScript-based documentation generator for E2B SDKs with automatic versioning, caching, and CI/CD integration.
+
+## Features
+
+- **Multi-SDK Support**: JS, Python, CLI, Code Interpreter, Desktop SDKs
+- **Automatic Version Discovery**: Detects and generates missing versions
+- **Intelligent Caching**: Skips reinstalling dependencies when lockfile unchanged
+- **Idempotent**: Safe to run repeatedly, only generates what's missing
+- **Full Visibility**: Complete logging of all subcommands for debugging
+- **Verification**: Validates generated docs before finalizing
+- **CI/CD Ready**: GitHub Actions integration with safety checks
+
+## Usage
+
+```bash
+# generate all SDKs, all versions
+pnpm run generate
+
+# generate specific SDK, latest version
+pnpm run generate --sdk js-sdk --version latest
+
+# generate specific version
+pnpm run generate --sdk python-sdk --version v2.8.0
+
+# limit to last N versions (useful for testing)
+pnpm run generate --sdk all --version all --limit 5
+
+# force regenerate existing versions (useful after config changes)
+pnpm run generate --sdk js-sdk --version all --force
+
+# combine flags
+pnpm run generate --sdk all --version all --limit 3 --force
+```
+
+## Architecture
+
+```
+src/
+├── cli.ts              # Entry point with CLI argument parsing
+├── generator.ts        # Core SDK generation orchestration
+├── navigation.ts       # Mintlify navigation builder
+├── types.ts            # TypeScript interfaces
+├── lib/
+│   ├── constants.ts    # Centralized magic strings
+│   ├── utils.ts        # Pure utility functions
+│   ├── git.ts          # Git operations (clone, tags)
+│   ├── checkout.ts     # Manages repo checkouts and version switching
+│   ├── versions.ts     # Version comparison and filtering
+│   ├── files.ts        # Markdown processing and flattening
+│   ├── install.ts      # Package manager abstraction
+│   └── verify.ts       # Post-generation validation
+└── generators/
+    ├── typedoc.ts      # JavaScript/TypeScript docs
+    ├── pydoc.ts        # Python docs
+    └── cli.ts          # CLI command docs
+```
+
+## Configuration
+
+SDKs are configured in `sdks.json`:
+
+```json
+{
+  "sdks": {
+    "js-sdk": {
+      "displayName": "SDK (JavaScript)",
+      "icon": "square-js",
+      "order": 1,
+      "repo": "https://github.com/e2b-dev/e2b.git",
+      "tagPattern": "e2b@",
+      "tagFormat": "e2b@{version}",
+      "generator": "typedoc",
+      "required": true,
+      "minVersion": "1.0.0",
+      "sdkPath": "packages/js-sdk"
+    }
+  }
+}
+```
+
+## Error Handling
+
+### Strict Safety Model
+
+1. **Required SDKs**: Any failure aborts workflow
+2. **Optional SDKs**: All versions failing aborts workflow
+3. **Partial failures**: Non-required SDK with some successes continues
+4. **Verification**: Post-generation validation ensures quality
+
+### Progressive Dependency Resolution
+
+For maximum compatibility across SDK versions:
+
+1. **Try pnpm install** - Primary package manager with caching
+2. **Try npm fallback** - Uses npm with `--force` and `--legacy-peer-deps`
+
+Each strategy visible in logs for debugging. If both strategies fail, workflow aborts.
+
+### What Gets Logged
+
+- ✅ Package manager output (pnpm/npm/poetry/pip)
+- ✅ Build tool output (TypeDoc, pydoc-markdown, CLI builds)
+- ✅ File operations (copying, flattening)
+- ✅ Validation results (empty files, missing frontmatter)
+- ✅ Final statistics (files, SDKs, versions)
+
+## Verification Checks
+
+Before finalizing, the generator verifies:
+
+1. **Generated Files**: No empty MDX files
+2. **Frontmatter**: All files have proper frontmatter
+3. **Structure**: Valid directory structure
+4. **docs.json**: Valid JSON with correct navigation structure
+
+## Testing
+
+```bash
+# run unit tests
+pnpm test
+
+# run with watch mode
+pnpm test:watch
+
+# type check
+npx tsc --noEmit
+```
+
+Tests cover:
+- Version comparison and filtering (10 tests)
+- File operations and title casing (5 tests)
+- Verification logic (7 tests)
+
+## CI/CD Integration
+
+The generator runs in GitHub Actions on:
+- Manual workflow dispatch
+- Automatic repository dispatch from SDK repos on release
+
+Safety features:
+- Validates all generated files before committing
+- Only commits if changes detected
+- Skips CI on doc updates (`[skip ci]` in commit message)
+- Full logging visible in workflow runs
+
+## Performance
+
+- **Checkout Reuse**: Repository cloned once, versions switched via git checkout
+- **Version Deduplication**: Batch comparison skips already-generated versions
+- **Parallel Generation**: Could process multiple versions concurrently (future enhancement)
+
+## Development
+
+```bash
+# install dependencies
+pnpm install
+
+# run generator locally
+pnpm run generate --sdk js-sdk --limit 1
+
+# run tests
+pnpm test
+```
+