Set up typedoc to generate documentation from jsdoc comments (#651)

## Summary:
[typedoc](https://typedoc.org/) can generate nice documentation sites from jsdoc comments.  This PR configures the tool to generate documentation.  It's themeable so if we don't like the theme we can swap it out for something else, see https://typedoc.org/guides/themes/.

TODO:
- [x] publish docs/ folder using the same gh-pages action as wonder-blocks

Issue: None

## Test plan:
- yarn build:docs
- open docs/index.html

<img width="1904" alt="Screen Shot 2023-04-14 at 5 04 56 PM" src="https://user-images.githubusercontent.com/1044413/232155355-51e39fd9-a128-4c5f-8d95-2bf4925bf6de.png">
<img width="1904" alt="Screen Shot 2023-04-14 at 5 04 29 PM" src="https://user-images.githubusercontent.com/1044413/232155370-1c949a4f-9ef7-43ad-8eca-bf44ddd1f31b.png">

The default theme supports dark mode out of the box:
<img width="1904" alt="Screen Shot 2023-04-14 at 5 31 18 PM" src="https://user-images.githubusercontent.com/1044413/232158556-3088e8fc-f724-4f7f-abd3-d246dc157ece.png">

Author: kevinbarabash

Reviewers: jeresig

Required Reviewers:

Approved By: jeresig

Checks: ✅ codecov/project, ✅ Test (macos-latest, 16.x), ✅ Test (macos-latest, 16.x), ✅ Lint, typecheck, and coverage check (ubuntu-latest, 16.x), ✅ Prime node_modules cache for primary configuration (ubuntu-latest, 16.x), ⏭  gerald, ✅ Lint, typecheck, and coverage check (ubuntu-latest, 16.x), ⏭  gerald, ✅ Prime node_modules cache for primary configuration (ubuntu-latest, 16.x), ✅ Test (macos-latest, 16.x), ✅ CodeQL, ✅ Lint, typecheck, and coverage check (ubuntu-latest, 16.x), ✅ Prime node_modules cache for primary configuration (ubuntu-latest, 16.x), ✅ Analyze (javascript), ✅ gerald, ⏭  dependabot

Pull Request URL: #651

Author: kevinbarabash

.changeset/real-bats-marry.md

@@ -0,0 +1,2 @@
+---
+---

.github/workflows/release.yml

@@ -41,6 +41,18 @@ jobs:
         with:
           node-version: 16.x
 
+      - name: Build Typedoc
+        # Generate nice docs inside "docs/" folder
+        run: yarn build:docs
+
+      - name: Deploy to GitHub pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          # The branch the action should deploy to.
+          branch: gh-pages
+          # The folder the action should deploy.
+          folder: docs
+
       - name: Create Release Pull Request or Publish to npm
         id: changesets
         uses: changesets/action@v1

.gitignore

@@ -1,6 +1,7 @@
 node_modules
 coverage
 dist
+docs
 !.vscode
 .DS_Store
 yarn-error.log

package.json

@@ -72,6 +72,7 @@
     "rollup-plugin-filesize": "^10.0.0",
     "rollup-plugin-preserve-shebangs": "^0.2.0",
     "superagent": "^5.3.1",
+    "typedoc": "^0.24.1",
     "typescript": "^4.9.5",
     "winston": "^3.8.2"
   },
@@ -83,6 +84,7 @@
     "build:prodsizecheck": "rollup -c build-settings/rollup.config.js --configPlatforms='browser' --configFormats='esm' --configEnvironment='production'",
     "build:types": "yarn tsc --build --verbose tsconfig-build.json && node -r @swc-node/register build-scripts/remove-test-types-from-dist.ts",
     "build:flowtypes": "node -r @swc-node/register build-scripts/gen-flow-types.ts",
+    "build:docs": "typedoc",
     "watch": "rollup -c build-settings/rollup.config.js --watch",
     "clean": "rm -rf packages/wonder-stuff-*/dist && rm -rf packages/wonder-stuff-*/node_modules && rm -f packages/*/tsconfig.tsbuildinfo",
     "coverage": "yarn run jest --coverage",
@@ -92,7 +94,7 @@
     "lint:pkg-json": "yarn npmPkgJsonLint ./packages/wonder-stuff-*",
     "publish:ci": "yarn run lint:pkg-json && node utils/pre-publish-check-ci.js && git diff --stat --exit-code HEAD && yarn build && yarn build:types && yarn build:flowtypes && changeset publish",
     "test": "yarn jest",
-    "typecheck": "tsc --project tsconfig-check.json",
+    "typecheck": "tsc",
     "nochangeset": "yarn changeset add --empty",
     "add:devdepbysha": "bash -c 'yarn add -W --dev \"git+https://[email protected]/Khan/$0.git#$1\"'"
   }

packages/wonder-stuff-render-server/src/types.ts

@@ -253,7 +253,7 @@ export type RenderGatewayOptions = {
      * A string that will be used to build an error response for a failed
      * render if all other error handling options fail.
      *
-     * If the sequence ${error} appears in the string, it will be replaced
+     * If the sequence `${error}` appears in the string, it will be replaced
      * with the JSONified error information. If it does not appear, the
      * JSONified error information will be omitted (useful if you don't want
      * to include that for users).

packages/wonder-stuff-testing/src/data-factory-for.ts

@@ -18,6 +18,7 @@ import {clone} from "@khanacademy/wonder-stuff-core";
  * that you have to check before setting the value.
  *
  * Example (shallow override):
+ * ```
  *     const BASE_OBJECT = {
  *         student: { ... },
  *         teacher: { ... },
@@ -31,8 +32,10 @@ import {clone} from "@khanacademy/wonder-stuff-core";
  *             ... other properties on `user`
  *         }
  *     });
+ * ```
  *
  * Example (deep update):
+ * ```
  *     const BASE_OBJECT = {
  *         student: { ... },
  *         teacher: { ... },
@@ -43,6 +46,7 @@ import {clone} from "@khanacademy/wonder-stuff-core";
  *         data.user.kaid = "new_kaid";
  *         data.user.id = "new_kaid";
  *     }
+ * ```
  */
 export const dataFactoryFor =
     <T>(baseObject: T): ((partialObject?: Partial<T>) => T) =>

tsconfig-check.json tsconfig.json

@@ -0,0 +1,13 @@
+{
+    "entryPoints": [
+        "packages/wonder-stuff-core/src/index.ts",
+        "packages/wonder-stuff-i18n/src/index.ts",
+        "packages/wonder-stuff-render-environment-jsdom/src/index.ts",
+        "packages/wonder-stuff-render-server/src/index.ts",
+        "packages/wonder-stuff-sentry/src/index.ts",
+        "packages/wonder-stuff-server/src/index.ts",
+        "packages/wonder-stuff-server-google/src/index.ts",
+        "packages/wonder-stuff-testing/src/index.ts",
+    ],
+    "out": "docs"
+}

typedoc.json

@@ -2675,6 +2675,11 @@ ansi-regex@^5.0.1:
   resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-5.0.1.tgz#082cb2c89c9fe8659a311a53bd6a4dc5301db304"
   integrity sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==
 
+ansi-sequence-parser@^1.1.0:
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/ansi-sequence-parser/-/ansi-sequence-parser-1.1.0.tgz#4d790f31236ac20366b23b3916b789e1bde39aed"
+  integrity sha512-lEm8mt52to2fT8GhciPCGeCXACSz2UwIN4X2e2LJSnZ5uAbn2/dsYdOmUXq0AtWS5cpAupysIneExOgH0Vd2TQ==
+
 ansi-styles@^3.2.1:
   version "3.2.1"
   resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-3.2.1.tgz#41fbb20243e50b12be0f04b8dedbf07520ce841d"
@@ -6644,6 +6649,11 @@ lru-cache@^7.4.4, lru-cache@^7.5.1, lru-cache@^7.7.1:
   resolved "https://registry.yarnpkg.com/lru-cache/-/lru-cache-7.18.3.tgz#f793896e0fd0e954a59dfdd82f0773808df6aa89"
   integrity sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA==
 
+lunr@^2.3.9:
+  version "2.3.9"
+  resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.9.tgz#18b123142832337dd6e964df1a5a7707b25d35e1"
+  integrity sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==
+
 magic-string@^0.25.7:
   version "0.25.9"
   resolved "https://registry.yarnpkg.com/magic-string/-/magic-string-0.25.9.tgz#de7f9faf91ef8a1c91d02c2e5314c8277dbcdd1c"
@@ -6746,6 +6756,11 @@ marked@^4.0.10:
   resolved "https://registry.yarnpkg.com/marked/-/marked-4.2.12.tgz#d69a64e21d71b06250da995dcd065c11083bebb5"
   integrity sha512-yr8hSKa3Fv4D3jdZmtMMPghgVt6TWbk86WQaWhDloQjRSQhMMYCAro7jP7VDJrjjdV8pxVxMssXS8B8Y5DZ5aw==
 
+marked@^4.2.12:
+  version "4.3.0"
+  resolved "https://registry.yarnpkg.com/marked/-/marked-4.3.0.tgz#796362821b019f734054582038b116481b456cf3"
+  integrity sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==
+
 mdurl@^1.0.1:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/mdurl/-/mdurl-1.0.1.tgz#fe85b2ec75a59037f2adfec100fd6c601761152e"
@@ -6872,6 +6887,13 @@ minimatch@^6.1.0, minimatch@^6.1.6:
   dependencies:
     brace-expansion "^2.0.1"
 
+minimatch@^7.1.3:
+  version "7.4.6"
+  resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-7.4.6.tgz#845d6f254d8f4a5e4fd6baf44d5f10c8448365fb"
+  integrity sha512-sBz8G/YjVniEz6lKPNpKxXwazJe4c19fEfV2GDMX6AjFz+MX9uDWIZW8XreVhkFW3fkIdTv/gxWr/Kks5FFAVw==
+  dependencies:
+    brace-expansion "^2.0.1"
+
 [email protected], minimist-options@^4.0.2:
   version "4.1.0"
   resolved "https://registry.yarnpkg.com/minimist-options/-/minimist-options-4.1.0.tgz#c0655713c53a8a2ebd77ffa247d342c40f010619"
@@ -8404,6 +8426,16 @@ shelljs@^0.8.4:
     interpret "^1.0.0"
     rechoir "^0.6.2"
 
+shiki@^0.14.1:
+  version "0.14.1"
+  resolved "https://registry.yarnpkg.com/shiki/-/shiki-0.14.1.tgz#9fbe082d0a8aa2ad63df4fbf2ee11ec924aa7ee1"
+  integrity sha512-+Jz4nBkCBe0mEDqo1eKRcCdjRtrCjozmcbTUjbPTX7OOJfEbTZzlUWlZtGe3Gb5oV1/jnojhG//YZc3rs9zSEw==
+  dependencies:
+    ansi-sequence-parser "^1.1.0"
+    jsonc-parser "^3.2.0"
+    vscode-oniguruma "^1.7.0"
+    vscode-textmate "^8.0.0"
+
 shimmer@^1.1.0, shimmer@^1.2.0:
   version "1.2.1"
   resolved "https://registry.yarnpkg.com/shimmer/-/shimmer-1.2.1.tgz#610859f7de327b587efebf501fb43117f9aff337"
@@ -9093,6 +9125,16 @@ typed-array-length@^1.0.4:
     for-each "^0.3.3"
     is-typed-array "^1.1.9"
 
+typedoc@^0.24.1:
+  version "0.24.1"
+  resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.24.1.tgz#6b793a800400d46ec1b93246d175608626275c0b"
+  integrity sha512-u4HwjZcSQhQSkkhLjgcs0ooAf6HrFVLDHHrwU2xZW8WxH0KnGZlNkaWxiOcK5Gagj7mxJSgwWx0dv8ACDAOXAQ==
+  dependencies:
+    lunr "^2.3.9"
+    marked "^4.2.12"
+    minimatch "^7.1.3"
+    shiki "^0.14.1"
+
 typescript-compiler@^1.4.1-2:
   version "1.4.1-2"
   resolved "https://registry.yarnpkg.com/typescript-compiler/-/typescript-compiler-1.4.1-2.tgz#ba4f7db22d91534a1929d90009dce161eb72fd3f"
@@ -9266,6 +9308,16 @@ vary@~1.1.2:
   resolved "https://registry.yarnpkg.com/vary/-/vary-1.1.2.tgz#2299f02c6ded30d4a5961b0b9f74524a18f634fc"
   integrity sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==
 
+vscode-oniguruma@^1.7.0:
+  version "1.7.0"
+  resolved "https://registry.yarnpkg.com/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz#439bfad8fe71abd7798338d1cd3dc53a8beea94b"
+  integrity sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==
+
+vscode-textmate@^8.0.0:
+  version "8.0.0"
+  resolved "https://registry.yarnpkg.com/vscode-textmate/-/vscode-textmate-8.0.0.tgz#2c7a3b1163ef0441097e0b5d6389cd5504b59e5d"
+  integrity sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==
+
 w3c-xmlserializer@^4.0.0:
   version "4.0.0"
   resolved "https://registry.yarnpkg.com/w3c-xmlserializer/-/w3c-xmlserializer-4.0.0.tgz#aebdc84920d806222936e3cdce408e32488a3073"