(WIP) [MMB-156] Add documentation comments and generate HTML documentation

.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/class-definitions.md

@@ -327,6 +327,8 @@ The most recent event emitted by [presence](https://ably.com/docs/presence-occup
 
 #### PresenceEvent
 
+TODO This type doesn’t exist in the codebase; it's defined inline in SpaceMember
+
 ```ts
 type PresenceEvent = {
   name: 'enter' | 'leave' | 'update' | 'present';
@@ -416,6 +418,8 @@ const otherLocations = await space.locations.getOthers()
 
 #### Location
 
+TODO this type doesn’t exist in the codebase; `unknown` is used
+
 Represents a location in an application.
 
 ```ts
@@ -424,6 +428,8 @@ type Location = string | Record<string, unknown> | null;
 
 #### LocationUpdate
 
+TODO this type doesn’t exist in the codebase; it’s defined inline in LocationEventMap
+
 Represents a change between locations for a given [`SpaceMember`](#spacemember).
 
 ```ts

docs/typedoc/intro.md

@@ -0,0 +1,7 @@
+# Ably Spaces SDK
+
+<!-- TODO needs proper content -->
+
+This is the documentation for Ably’s Spaces SDK. Start with the documentation for the SDK’s {@link default | default export}.
+
+For alternative documentation, see our [documentation website](https://ably.com/docs/spaces).

package.json

@@ -19,7 +19,8 @@
     "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",
     "prepare": "husky install",
-    "examples:locks": "ts-node ./examples/locks.ts"
+    "examples:locks": "ts-node ./examples/locks.ts",
+    "docs": "typedoc"
   },
   "exports": {
     "import": "./dist/mjs/index.js",
@@ -57,7 +58,8 @@
     "vitest": "^0.34.3"
   },
   "dependencies": {
-    "nanoid": "^4.0.2"
+    "nanoid": "^4.0.2",
+    "typedoc": "^0.25.1"
   },
   "peerDependencies": {
     "ably": "^1.2.43"