feat(): experimental support for typedoc generation

Run `npm run typedoc` to generate docs in `typedoc-docs` dir.

I thought I'd take a few mins and set this up.  It was _mostly_ straightforward, except:

1. Figuring out the "entry point" for each package was difficult until I realized `.js` entry points are assumed to be compiled, and thus require a `sourceMappingUrl` reference. IMO this is probably a bug in TypeDoc
2. The `sourceMappingUrl` must reference an external sourcemap file; not an inline source map.  If it's an inline source map, the system tries to `fs.open` a large data-url.
3. The babel config does not control whether external sourcemaps are created; `@babel/cli` does. So I needed to change those.
4. Practically speaking, I don't see any drawback to external sourcemaps _yet_
5. TypeDoc has poor support for cross-package type references in monorepos, and I had to add a plugin which implements a workaround
6. Per some suggestions in the docs, I modified the order of references in the root `tsconfig.json` to start with "the biggest one first"

I didn't modify any types or docstrings anywhere.

.gitignore

@@ -61,3 +61,4 @@ packages/*/LICENSE
 local_appium_home
 jsdoc-out
 *.tgz
+typedoc-docs

babel.config.json

@@ -12,7 +12,7 @@
   ],
   "plugins": ["source-map-support"],
   "comments": false,
-  "sourceMaps": "both",
+  "sourceMaps": true,
   "env": {
     "coverage": {
       "plugins": [

package.json

@@ -60,6 +60,7 @@
     "test:e2e": "lerna run --max-buffer=128 test:e2e",
     "test:smoke": "smoker --all test:smoke",
     "test:unit": "lerna run test",
+    "typedoc": "typedoc",
     "upload": "gulp github-upload",
     "preversion": "run-s clean:artifacts build sync-pkgs && git add -A packages/appium/README.md packages/*/package.json",
     "zip": "zip -qr ./appium.zip ./packages/appium",
@@ -125,6 +126,8 @@
     "sinon-chai": "3.7.0",
     "sync-monorepo-packages": "0.3.5",
     "through2": "4.0.2",
+    "typedoc": "0.23.10",
+    "typedoc-plugin-resolve-crossmodule-references": "0.3.0",
     "typescript": "4.7.4",
     "validate.js": "0.13.1",
     "webdriverio": "7.26.0",

packages/appium/package.json

@@ -41,7 +41,7 @@
     "types"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "build": "babel lib --source-maps --root-mode=upward --out-dir=build/lib",
     "build:docs": "node docs/scripts/build-docs.js",
     "build:docs:cli": "node docs/scripts/gen-cli-args-docs.js",
     "build:docs:assets": "node docs/scripts/copy-assets.js",
@@ -107,5 +107,8 @@
     "access": "public",
     "tag": "next"
   },
+  "typedoc": {
+    "entryPoint": "./build/lib/main.js"
+  },
   "gitHead": "5c7af8ee73078018e4ec52fccf19fe3f77249d72"
 }

packages/base-driver/package.json

@@ -23,6 +23,7 @@
   },
   "license": "Apache-2.0",
   "author": "https://github.com/appium",
+  "types": "./build/lib/index.d.ts",
   "directories": {
     "lib": "lib"
   },
@@ -34,7 +35,7 @@
     "build"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "build": "babel lib --source-maps --root-mode=upward --out-dir=build/lib",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
@@ -76,6 +77,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "types": "./build/lib/index.d.ts",
-  "gitHead": "5c7af8ee73078018e4ec52fccf19fe3f77249d72"
+  "gitHead": "5c7af8ee73078018e4ec52fccf19fe3f77249d72",
+  "typedoc": {
+    "entryPoint": "./build/lib/index.js"
+  }
 }

packages/base-plugin/package.json

@@ -2,6 +2,7 @@
   "name": "@appium/base-plugin",
   "version": "1.10.5",
   "description": "The base plugin used to create Appium 2.0 plugins",
+  "homepage": "https://appium.io",
   "bugs": {
     "url": "https://github.com/appium/appium/issues"
   },
@@ -12,6 +13,7 @@
   },
   "license": "Apache-2.0",
   "author": "https://github.com/appium",
+  "types": "./build/lib/plugin.d.ts",
   "directories": {
     "lib": "./lib"
   },
@@ -21,7 +23,7 @@
     "index.js"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "build": "babel lib --source-maps --root-mode=upward --out-dir=build/lib",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
@@ -37,11 +39,13 @@
     "node": ">=14",
     "npm": ">=8"
   },
-  "types": "./build/lib/plugin.d.ts",
   "gitHead": "5c7af8ee73078018e4ec52fccf19fe3f77249d72",
   "tags": [
     "appium"
   ],
+  "typedoc": {
+    "entryPoint": "./build/lib/plugin.js"
+  },
   "homepage": "https://appium.io",
   "keywords": [
     "automation",

packages/doctor/package.json

@@ -37,8 +37,8 @@
     "build"
   ],
   "scripts": {
-    "build:lib": "babel lib --root-mode=upward --out-dir=build/lib",
-    "build:bin": "babel bin --root-mode=upward --out-dir=build/bin",
+    "build:lib": "babel lib --source-maps --root-mode=upward --out-dir=build/lib",
+    "build:bin": "babel bin --source-maps --root-mode=upward --out-dir=build/bin",
     "build": "run-s build:*",
     "dev": "run-p \"build:lib -- --watch\" \"build:bin -- --watch\"",
     "fix": "npm run lint -- --fix",

packages/docutils/package.json

@@ -35,8 +35,8 @@
   ],
   "scripts": {
     "build": "npm run build:sources && npm run build:test",
-    "build:sources": "babel lib --root-mode=upward --out-dir=build/lib",
-    "build:test": "babel test --root-mode=upward --out-dir=build/test --copy-files",
+    "build:sources": "babel lib --source-maps --root-mode=upward --out-dir=build/lib",
+    "build:test": "babel test --source-maps --root-mode=upward --out-dir=build/test --copy-files",
     "dev": "npm run build:sources -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",

packages/execute-driver-plugin/package.json

@@ -29,7 +29,7 @@
     "index.js"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "build": "babel lib --source-maps --root-mode=upward --out-dir=build/lib",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",

packages/fake-driver/package.json

@@ -36,7 +36,7 @@
     "test/fixtures"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib --copy-files",
+    "build": "babel lib --source-maps --root-mode=upward --out-dir=build/lib --copy-files",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",

packages/fake-plugin/package.json

@@ -23,7 +23,7 @@
     "build"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "build": "babel lib --source-maps --root-mode=upward --out-dir=build/lib",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",

packages/images-plugin/package.json

@@ -29,7 +29,7 @@
     "index.js"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "build": "babel lib --source-maps --root-mode=upward --out-dir=build/lib",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",

packages/opencv/package.json

@@ -33,7 +33,7 @@
     "build"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "build": "babel lib --source-maps --root-mode=upward --out-dir=build/lib",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",

packages/relaxed-caps-plugin/package.json

@@ -21,7 +21,7 @@
     "build"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "build": "babel lib --source-maps --root-mode=upward --out-dir=build/lib",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",

packages/schema/package.json

@@ -31,7 +31,7 @@
   ],
   "scripts": {
     "build": "run-s build:*",
-    "build:distfiles": "babel lib --root-mode=upward --out-dir=build",
+    "build:distfiles": "babel lib --source-maps --root-mode=upward --out-dir=build",
     "build:schema-json": "node ./scripts/generate-schema-json.js",
     "dev": "npm run build:distfiles -- --watch",
     "fix": "npm run lint -- --fix",
@@ -51,5 +51,8 @@
   "publishConfig": {
     "access": "public"
   },
+  "typedoc": {
+    "entryPoint": "./build/index.js"
+  },
   "gitHead": "5c7af8ee73078018e4ec52fccf19fe3f77249d72"
 }

packages/support/package.json

@@ -33,7 +33,7 @@
     "build"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "build": "babel lib --source-maps --root-mode=upward --out-dir=build/lib",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
@@ -110,6 +110,9 @@
     "access": "public"
   },
   "gitHead": "5c7af8ee73078018e4ec52fccf19fe3f77249d72",
+  "typedoc": {
+    "entryPoint": "./build/lib/index.js"
+  },
   "overrides": {
     "jpeg-js": "0.4.4"
   }

packages/test-support/package.json

@@ -38,7 +38,7 @@
     "build"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "build": "babel lib --source-maps --root-mode=upward --out-dir=build/lib",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",

packages/types/package.json

@@ -47,5 +47,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "5c7af8ee73078018e4ec52fccf19fe3f77249d72"
+  "gitHead": "5c7af8ee73078018e4ec52fccf19fe3f77249d72",
+  "typedoc": {
+    "entryPoint": "./lib/index.ts"
+  }
 }

packages/universal-xml-plugin/package.json

@@ -29,7 +29,7 @@
     "lib"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "build": "babel lib --source-maps --root-mode=upward --out-dir=build/lib",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",

tsconfig.json

@@ -27,10 +27,13 @@
       "path": "packages/base-plugin"
     },
     {
-      "path": "packages/test-support"
+      "path": "packages/schema"
     },
     {
-      "path": "packages/appium"
+      "path": "packages/types"
+    },
+    {
+      "path": "packages/test-support"
     },
     {
       "path": "packages/fake-plugin"

typedoc.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["./packages/appium", "./packages/base-driver", "./packages/support", "./packages/types", "./packages/base-plugin"],
+  "entryPointStrategy": "packages",
+  "name": "Appium",
+  "includeVersion": false,
+  "tsconfig": "./tsconfig.json",
+  "out": "typedoc-docs",
+  "cleanOutputDir": true,
+  "plugin": ["typedoc-plugin-resolve-crossmodule-references"]
+}