Invoke typedoc to produce browsable JS API documentation (#4757)

Replaces the annotation processor previously used with a doclet
implementation. This still emits a .d.ts file using Java
mirror/element types for accurate type information, but now is able
to traverse Javadoc trees as well, and produces corresponding
typedoc tags or markdown. The typedoc tool now generates HTML for
deployment to the Deephaven docs website.

Additionally, this branch produces a tarball suitable for deployment
as an npm module, containing only those generated types. However,
this output is still untested.

.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"]
+  }
+}