Use TypeDoc to generate HTML documentation and upload to sdk.ably.com

This is largely copied from the way we do things in ably-js (as of its
commit 76a5475).

I’ve made a couple of tweaks to the config, though:

- Added all types (except Project, which I have no idea how to
  document, and TypeLiteral, which would require us to split out every
  type literal into its own type, which we don’t want) to
  requiredToBeDocumented. I took the list from [1].

- Excluded internal and private stuff from documentation (see ccafd10).

[1] https://github.com/TypeStrong/typedoc/blob/f2d2abe054feca91b89c00c33e1d726bbda85dcb/src/lib/models/reflections/kind.ts#L7

.github/workflows/dev-ci.yml

@@ -52,3 +52,31 @@ jobs:
           node-version: 18
       - run: npm ci
       - run: npm run build
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      deployments: write
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v1
+        with:
+          node-version: 18
+      - name: Install Package Dependencies
+        run: npm ci
+      - name: Build SDK
+        run: npm run build
+      - name: Build Documentation
+        run: npm run docs
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        with:
+          aws-region: eu-west-2
+          role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-spaces
+          role-session-name: "${{ github.run_id }}-${{ github.run_number }}"
+      - name: Upload Documentation
+        uses: ably/sdk-upload-action@v1
+        with:
+          sourcePath: docs/typedoc/generated
+          githubToken: ${{ secrets.GITHUB_TOKEN }}
+          artifactName: typedoc

.gitignore

@@ -5,6 +5,7 @@ node_modules/
 .vscode
 coverage
 .env
+docs/typedoc/generated/
 
 # Local Netlify folder
 .netlify

docs/typedoc/intro.md

@@ -0,0 +1,5 @@
+# Ably Spaces SDK
+
+This is the API reference for Ably’s Spaces SDK, generated with [TypeDoc](https://typedoc.org/).
+
+To find out more about Spaces and how to get started, visit the [Ably documentation website](https://ably.com/docs/spaces).

package.json

@@ -18,7 +18,8 @@
     "build:mjs": "npx tsc --project tsconfig.mjs.json && cp res/package.mjs.json dist/mjs/package.json",
     "build:cjs": "npx tsc --project tsconfig.cjs.json && cp res/package.cjs.json dist/cjs/package.json",
     "build:iife": "rm -rf dist/iife && npx tsc --project tsconfig.iife.json && rollup -c",
-    "examples:locks": "ts-node ./examples/locks.ts"
+    "examples:locks": "ts-node ./examples/locks.ts",
+    "docs": "typedoc"
   },
   "exports": {
     "import": "./dist/mjs/index.js",
@@ -52,6 +53,7 @@
     "prettier": "^2.8.3",
     "rollup": "^3.28.0",
     "ts-node": "^10.9.1",
+    "typedoc": "^0.25.2",
     "typescript": "^4.9.5",
     "vitest": "^0.34.3"
   },

typedoc.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["dist/mjs/index.d.ts"],
+  "excludeInternal": true,
+  "excludePrivate": true,
+  "includeVersion": true,
+  "out": "docs/typedoc/generated",
+  "readme": "docs/typedoc/intro.md",
+  "requiredToBeDocumented": [
+    "Accessor",
+    "CallSignature",
+    "Class",
+    "Constructor",
+    "ConstructorSignature",
+    "Enum",
+    "EnumMember",
+    "Function",
+    "GetSignature",
+    "IndexSignature",
+    "Interface",
+    "Method",
+    "Module",
+    "Namespace",
+    "Parameter",
+    "Property",
+    "Reference",
+    "SetSignature",
+    "TypeAlias",
+    "TypeParameter",
+    "Variable",
+  ],
+  "treatWarningsAsErrors": true,
+  "validation": true
+}