Generate SDK reference

.github/scripts/is_new_sdk_ref.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# This script checks for diffs in the js/ and python/ directory.
+# If there are diffs, it means we need to generate new SDK references.
+if git diff --name-only HEAD^ | grep -q '^js/\|^python/'; then
+    echo "true"
+else
+    echo "false"
+fi

.github/workflows/generate_sdk_ref.yml

@@ -0,0 +1,106 @@
+name: Generate SDK references
+
+on:
+  workflow_dispatch:
+  workflow_call:
+  # Remove after testing
+  push:
+    branches:
+      - generate-api-reference-for-code-interpreter-sdk-e2b-1235
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+permissions:
+  contents: write
+
+jobs:
+  is_new_sdk_ref:
+    name: Is new SDK reference?
+    runs-on: ubuntu-latest
+    outputs:
+      new_sdk_ref: ${{ steps.sdk-changes.outputs.new_sdk_ref }}
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 2
+
+      - name: Check if SDK changes
+        id: sdk-changes
+        run: |
+          IS_NEW_sdk_REF=$(./.github/scripts/is_new_sdk_ref.sh)
+          echo "new_sdk_ref=$IS_NEW_sdk_REF" >> "$GITHUB_OUTPUT"
+
+  sdk-changes:
+    name: SDK changes
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v3
+        id: pnpm-install
+        with:
+          version: 9.5
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: "20.x"
+          registry-url: "https://registry.npmjs.org"
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Configure pnpm
+        run: |
+          pnpm config set auto-install-peers true
+          pnpm config set exclude-links-from-lockfile true
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Set up Python
+        id: setup-python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.8"
+
+      - name: Install and configure Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: 1.5.1
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          installer-parallel: true
+
+      - name: Install dependencies
+        working-directory: ./packages/python-sdk
+        run: poetry install --no-interaction --no-root
+
+      - name: Generate Python SDK reference
+        id: python-sdk-ref
+        working-directory: ./python
+        run: |
+          source .venv/bin/activate
+          ./scripts/generate_sdk_ref.sh
+
+      - name: Generate JS SDK reference
+        id: js-sdk-ref
+        working-directory: ./js
+        run: ./scripts/generate_sdk_ref.sh
+
+      - name: Show docs file structure
+        run: tree apps/web/src/app/\(docs\)/docs/sdk-reference
+
+      - name: Commit new SDK reference versions
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |  
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add ./sdk-reference
+          git commit -m "[skip ci] Release new SDK reference doc versions" || exit 0
+          git push

.github/workflows/release.yml

@@ -319,6 +319,30 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  is_new_sdk_ref:
+    name: Is new SDK reference?
+    runs-on: ubuntu-latest
+    outputs:
+      new_sdk_ref: ${{ steps.sdk-changes.outputs.new_sdk_ref }}
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 2
+
+      - name: Check if SDK changes
+        id: sdk-changes
+        run: |
+          IS_NEW_SDK_REF=$(./.github/scripts/is_new_sdk_ref.sh)
+          echo "new_sdk_ref=$IS_NEW_SDK_REF" >> "$GITHUB_OUTPUT"
+
+  generate_sdk_ref:
+    name: Generate SDK reference
+    needs: [is_release, python-tests, js-tests, is_new_sdk_ref]
+    if: (!cancelled()) && !contains(needs.*.result, 'failure') && needs.is_release.outputs.release == 'true' && needs.is_new_sdk_ref.outputs.new_sdk_ref == 'true'
+    uses: ./.github/workflows/generate_sdk_ref.yml
+    secrets: inherit
+
   report-failure:
     needs: [python-tests, js-tests, release]
     if: failure()

js/package.json

@@ -41,6 +41,8 @@
     "knip": "^5.25.1",
     "npm-check-updates": "^16.14.20",
     "tsup": "^8.1.0",
+    "typedoc": "^0.26.8",
+    "typedoc-plugin-markdown": "^4.2.7",
     "typescript": "^5.5.3",
     "vitest": "^2.0.1"
   },

js/scripts/CustomMarkdownTheme.js

@@ -0,0 +1,64 @@
+const { MarkdownTheme, MarkdownPageEvent } = require('typedoc-plugin-markdown')
+
+function load(app) {
+  // Listen to the render event
+  app.renderer.on(MarkdownPageEvent.END, (page) => {
+    // Remove Markdown links from the document contents
+    page.contents = removeMarkdownLinks(
+      removeFirstNLines(
+        convertH5toH3(removeLinesWithConditions(page.contents)),
+        6
+      )
+    )
+  })
+}
+
+// this is a hacky way to make methods in the js-sdk sdk reference look more prominent
+function convertH5toH3(text) {
+  return text.replace(/^##### (.*)$/gm, '### $1')
+}
+
+// Function to remove Markdown-style links
+function removeMarkdownLinks(text) {
+  // Regular expression to match Markdown links [text](url)
+  return text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '$1') // Replace with just the link text
+}
+
+function removeFirstNLines(text, n, condition) {
+  // Split the text into lines, then join back excluding the first four lines
+  return text.split('\n').slice(n).join('\n')
+}
+
+// Function to remove lines based on conditions
+function removeLinesWithConditions(text) {
+  const lines = text.split('\n')
+  const filteredLines = []
+
+  for (let i = 0; i < lines.length; i++) {
+    // Check if the current line starts with "#### Extends" or "###### Overrides"
+    if (
+      lines[i].startsWith('#### Extends') ||
+      lines[i].startsWith('###### Overrides') ||
+      lines[i].startsWith('###### Inherited from')
+    ) {
+      // If it does, skip this line and the next three lines
+      i += 3 // Skip this line and the next three
+      continue
+    }
+
+    if (lines[i].startsWith('##### new')) {
+      // avoid promoting constructors
+      i += 1
+      continue
+    }
+
+    // If not removed, add the line to filteredLines
+    filteredLines.push(convertH5toH3(lines[i]))
+  }
+
+  // Join the filtered lines back into a single string
+  return filteredLines.join('\n')
+}
+
+// Export the load function
+module.exports = { load }

js/scripts/generate_sdk_ref.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# This script generates the Code Interpreter JS SDK reference markdown files
+# Run it in the `js/` directory
+
+# generate raw SDK reference markdown files
+npx typedoc
+
+PKG_VERSION="v$(node -p "require('./package.json').version")"
+ROUTES_DIR="../sdk-reference/code-interpreter-js-sdk/${PKG_VERSION}"
+mkdir -p "${ROUTES_DIR}"
+
+rm -rf sdk_ref/README.md
+
+# Flatten the sdk_ref directory by moving all nested files to the root level and remove empty subdirectories
+find sdk_ref -mindepth 2 -type f | while read -r file; do
+    mv "$file" sdk_ref/
+done
+find sdk_ref -type d -empty -delete
+
+# Transfrom top level MD files into folders of the same name with page.mdx inside
+find sdk_ref -maxdepth 1 -type f -name "*.md" | while read -r file; do
+    # Extract the filename without extension
+    filename=$(basename "$file" .md)
+    # Create the directory of the same name in sdk_ref
+    mkdir -p "sdk_ref/${filename}"
+    # Move the file inside the newly created directory
+    mv "$file" "sdk_ref/${filename}/page.mdx"
+done
+
+cp -r sdk_ref/* "${ROUTES_DIR}"
+
+rm -rf sdk_ref

js/typedoc.json

@@ -0,0 +1,31 @@
+{
+  "out": "sdk_ref",
+  "plugin": ["typedoc-plugin-markdown", "./scripts/CustomMarkdownTheme.js"],
+  "exclude": ["**/*.spec.ts"],
+  "entryPoints": [
+    "src/index.ts",
+    "src/charts.ts",
+    "src/consts.ts",
+    "src/messaging.ts",
+    "src/sandbox.ts"
+  ],
+  "excludeExternals": true,
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "navigation": {
+    "includeGroups": false,
+    "includeCategories": false
+  },
+  "outputFileStrategy": "modules",
+  "readme": "none",
+  "disableSources": true,
+  // typedoc-plugin-markdown options
+  "classPropertiesFormat": "table",
+  "typeDeclarationFormat": "table",
+  "enumMembersFormat": "table",
+  "parametersFormat": "table",
+  "expandParameters": true,
+  "useCodeBlocks": true,
+  "hidePageTitle": true,
+  "hideBreadcrumbs": true
+}