Invoke typedoc to produce browsable JS API documentation

.github/workflows/docs-ci.yml

@@ -65,6 +65,57 @@ jobs:
           remote_user: ${{ secrets.DOCS_USER }}
           remote_key: ${{ secrets.DEEPHAVEN_CORE_SSH_KEY }}
 
+  typedoc:
+    runs-on: ubuntu-22.04
+    concurrency:
+      group: typedoc-${{ github.workflow }}-${{ github.ref }}
+      # We don't want to cancel in-progress jobs against main because that might leave the upload in a bad state.
+      cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup JDK 11
+        id: setup-java-11
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: '11'
+
+      - name: Setup JDK 17
+        id: setup-java-17
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
+      - name: Set JAVA_HOME
+        run: echo "JAVA_HOME=${{ steps.setup-java-11.outputs.path }}" >> $GITHUB_ENV
+
+      - name: Run typedoc on JS API
+        uses: burrunan/gradle-cache-action@v1
+        with:
+          job-id: typedoc
+          arguments: --scan :web-client-api:types:typedoc
+          gradle-version: wrapper
+      - name: Upload JavaScript/TypeScript docs
+        if: ${{ github.ref == 'refs/heads/main' }}
+        uses: actions/upload-artifact@v3
+        with:
+          name: typedoc
+          path: 'web/client-api/types/build/documentation/'
+      - name: Deploy JavaScript/TypeScript docs
+        if: ${{ github.ref == 'refs/heads/main' }}
+        uses: burnett01/[email protected]
+        with:
+          switches: -avzr --delete
+          path: web/client-api/docs/build/documentation/
+          remote_path: deephaven-core/client-api/javascript/
+          remote_host: ${{ secrets.DOCS_HOST }}
+          remote_port: ${{ secrets.DOCS_PORT }}
+          remote_user: ${{ secrets.DOCS_USER }}
+          remote_key: ${{ secrets.DEEPHAVEN_CORE_SSH_KEY }}
+
   pydoc:
     runs-on: ubuntu-22.04
     concurrency:

settings.gradle

@@ -416,6 +416,10 @@ Closure configureWebModule = {
 
 webMods.collect({ project(":$it")}).each configureWebModule
 
+include ':web-client-api:types'
+project(':web-client-api:types').projectDir = file('web/client-api/types')
+
+
 buildCache {
     local {
         removeUnusedEntriesAfterDays = 4

web/client-api/client-api.gradle

@@ -6,14 +6,16 @@ apply from: "$rootDir/gradle/web-client.gradle"
 
 configurations {
     js
+    dts
+    typescriptDoclet
 }
 
 dependencies {
     implementation project(':web-shared-beans')
     implementation project(':web-client-backplane')
 
-    implementation 'com.vertispan.tsdefs:jsinterop-ts-defs-annotations:1.0.0-RC2'
-    annotationProcessor 'com.vertispan.tsdefs:jsinterop-ts-defs-processor:1.0.0-RC2'
+    implementation 'com.vertispan.tsdefs:jsinterop-ts-defs-annotations:1.0.0-RC3'
+    typescriptDoclet 'com.vertispan.tsdefs:jsinterop-ts-defs-doclet:1.0.0-RC3'
 
     implementation 'com.vertispan.nio:gwt-nio:1.0-alpha-1'
 
@@ -36,10 +38,23 @@ def gwtOutput = tasks.register('gwtOutput', Sync) {
     into jsOutput
 }
 
+def dtsOutput = layout.buildDirectory.dir('ts-types');
+def tsDefs = tasks.register('typescriptDefinitions', Javadoc) {
+    dependsOn 'compileJava'
+    source = sourceSets.main.allJava
+    options.classpath = sourceSets.main.compileClasspath.files as List
+    destinationDir = dtsOutput.get().asFile
+    options.docletpath = (configurations.typescriptDoclet.files as List) + (sourceSets.main.compileClasspath.files as List)
+    options.doclet = 'com.vertispan.tsdefs.doclet.TsDoclet'
+}
+
 artifacts {
     js(jsOutput) {
         builtBy gwtOutput
     }
+    dts(dtsOutput) {
+        builtBy tsDefs
+    }
 }
 
 project.tasks.getByName('quick').dependsOn project.tasks.withType(de.esoco.gwt.gradle.task.GwtCompileTask)

web/client-api/types/build.gradle

@@ -0,0 +1,52 @@
+plugins {
+    id 'com.bmuschko.docker-remote-api'
+    id 'io.deephaven.project.register'
+}
+
+configurations {
+    dts
+}
+dependencies {
+    dts project(path: ':web-client-api', configuration: 'dts')
+}
+
+Docker.registerDockerTask(project, 'typedoc') {
+    copyIn {
+        from(configurations.dts) {
+            into 'dist'
+        }
+        from 'tsconfig.json'
+        from 'package.json'
+        from 'package-lock.json'
+
+        from('src/main/docker') {
+            include 'theme.css'
+        }
+    }
+    dockerfile {
+        // share the common base image to keep it simple
+        from 'deephaven/node:local-build'
+
+        copyFile('.', '/project')
+
+        runCommand('''set -eux; \\
+                      cd /project/; \\
+                      mv dist/types.d.ts dist/index.d.ts; \\
+                      npm ci; \\
+                      npm pack; \\
+                      mkdir /out; \\
+                      mv deephaven-jsapi-types*.tgz /out/; \\
+                      node_modules/.bin/typedoc dist/index.d.ts \\
+                           --out /out/documentation \\
+                           --skipErrorChecking \\
+                           --hideGenerator \\
+                           --disableSources \\
+                           --customCss theme.css; \\
+                      ''')
+    }
+    parentContainers = [ Docker.registryTask(project, 'node') ] // deephaven/node
+    containerOutPath = '/out'
+    copyOut {
+        into "$buildDir/"
+    }
+}

web/client-api/types/gradle.properties

@@ -0,0 +1 @@
+io.deephaven.project.ProjectType=BASIC

web/client-api/types/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@deephaven/jsapi-types",
+  "version": "1.0.0-dev1",
+  "description": "Deephaven JSAPI Types",
+  "author": "Deephaven Data Labs LLC",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deephaven/deephaven-core.git",
+    "directory": "web/client-api/types"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "devDependencies": {
+    "typedoc": "^0.24.8",
+    "typescript": "^5.1.6"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

web/client-api/types/src/main/docker/theme.css

@@ -0,0 +1,18 @@
+:root {
+    --dark-color-background: #040427;
+    --dark-color-background-secondary: #0d1b37;
+    --dark-color-background-warning: #fffbef;
+    --dark-color-warning-text: #463b19;
+    --dark-color-accent: #24405a;
+    --dark-color-active-menu-item: #2f546c;
+    --dark-color-text: #f0f9fb;
+    --dark-color-text-aside: #d3d3d3;
+    --dark-color-link: #65c6da;
+    --dark-color-ts-project: #b7a9f6;
+    --dark-color-ts-enum: #f4d93e;
+    --dark-color-ts-variable: #b2e3ed;
+    --dark-color-ts-function: #d5cdfa;
+    --dark-color-ts-class: #93d7e5;
+    --dark-color-ts-interface: #afd685;
+    --dark-color-ts-type-alias: #f27596;
+}

web/client-api/types/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": ["dist/index.d.ts"],
+  "compilerOptions": {
+    "target": "es5",
+    "lib": ["es5","es2015", "DOM"]
+  }
+}