From 895439dbfbab34d2a1ab43c2f1805a5ffa482c0a Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Fri, 26 Apr 2024 12:29:52 +0100 Subject: [PATCH 01/11] Added typedoc to package reqs. Setup basic typedoc config. Added landing page for typedoc. --- .github/workflows/docks.yml | 42 ++++++++++++++++++++ package-lock.json | 76 +++++++++++++++++++++++++++++++++++-- package.json | 1 + tsconfig.base.json | 2 +- typedoc/landing-page.md | 6 +++ 5 files changed, 123 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/docks.yml create mode 100644 typedoc/landing-page.md diff --git a/.github/workflows/docks.yml b/.github/workflows/docks.yml new file mode 100644 index 00000000..f9e71842 --- /dev/null +++ b/.github/workflows/docks.yml @@ -0,0 +1,42 @@ +name: API Reference +on: + pull_request: + push: + branches: + - main + tags: + - '*' + +jobs: + build: + runs-on: ubuntu-latest + permissions: + deployments: write + id-token: write + steps: + - uses: actions/checkout@v3 + + - name: Use Node.js 20.x + uses: actions/setup-node@v3 + with: + node-version: 20.x + + - name: Install Package Dependencies + run: npm ci + + - 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-ably-js + role-session-name: "${{ github.run_id }}-${{ github.run_number }}" + + - name: Upload Documentation + uses: ably/sdk-upload-action@v1 + with: + sourcePath: typedoc/generated + githubToken: ${{ secrets.GITHUB_TOKEN }} + artifactName: typedoc diff --git a/package-lock.json b/package-lock.json index ff83aca6..ce9e679f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -22,6 +22,7 @@ "eslint-plugin-react-refresh": "^0.4.6", "eslint-plugin-security": "^1.7.1", "prettier": "^3.2.5", + "typedoc": "^0.25.13", "typescript": "^5.4.5", "vitest": "^1.4.0" }, @@ -1296,6 +1297,12 @@ "node": ">=8" } }, + "node_modules/ansi-sequence-parser": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz", + "integrity": "sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==", + "dev": true + }, "node_modules/ansi-styles": { "version": "4.3.0", "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", @@ -3467,13 +3474,19 @@ } }, "node_modules/lru-cache": { - "version": "10.2.0", - "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.2.0.tgz", - "integrity": "sha512-2bIM8x+VAf6JT4bKAljS1qUWgMsqZRPGJS6FSahIMPVvctcNhyVp7AJu7quxOW9jwkryBReKZY5tY5JYv2n/7Q==", + "version": "10.2.1", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.2.1.tgz", + "integrity": "sha512-tS24spDe/zXhWbNPErCHs/AGOzbKGHT+ybSBqmdLm8WZ1xXLWvH8Qn71QPAlqVhd0qUTWjy+Kl9JmISgDdEjsA==", "engines": { "node": "14 || >=16.14" } }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true + }, "node_modules/magic-string": { "version": "0.30.9", "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.9.tgz", @@ -3486,6 +3499,18 @@ "node": ">=12" } }, + "node_modules/marked": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz", + "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==", + "dev": true, + "bin": { + "marked": "bin/marked.js" + }, + "engines": { + "node": ">= 12" + } + }, "node_modules/merge-stream": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz", @@ -4341,6 +4366,18 @@ "node": ">=8" } }, + "node_modules/shiki": { + "version": "0.14.7", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.14.7.tgz", + "integrity": "sha512-dNPAPrxSc87ua2sKJ3H5dQ/6ZaY8RNnaAqK+t0eG7p0Soi2ydiqbGOTaZCqaYvA/uZYfS1LJnemt3Q+mSfcPCg==", + "dev": true, + "dependencies": { + "ansi-sequence-parser": "^1.1.0", + "jsonc-parser": "^3.2.0", + "vscode-oniguruma": "^1.7.0", + "vscode-textmate": "^8.0.0" + } + }, "node_modules/side-channel": { "version": "1.0.6", "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.0.6.tgz", @@ -4737,6 +4774,27 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/typedoc": { + "version": "0.25.13", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.25.13.tgz", + "integrity": "sha512-pQqiwiJ+Z4pigfOnnysObszLiU3mVLWAExSPf+Mu06G/qsc3wzbuM56SZQvONhHLncLUhYzOVkjFFpFfL5AzhQ==", + "dev": true, + "dependencies": { + "lunr": "^2.3.9", + "marked": "^4.3.0", + "minimatch": "^9.0.3", + "shiki": "^0.14.7" + }, + "bin": { + "typedoc": "bin/typedoc" + }, + "engines": { + "node": ">= 16" + }, + "peerDependencies": { + "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x" + } + }, "node_modules/typescript": { "version": "5.4.5", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.4.5.tgz", @@ -4928,6 +4986,18 @@ } } }, + "node_modules/vscode-oniguruma": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz", + "integrity": "sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==", + "dev": true + }, + "node_modules/vscode-textmate": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-8.0.0.tgz", + "integrity": "sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==", + "dev": true + }, "node_modules/which": { "version": "2.0.2", "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", diff --git a/package.json b/package.json index 613d9b1a..a9e5b4a6 100644 --- a/package.json +++ b/package.json @@ -46,6 +46,7 @@ "eslint-plugin-react-refresh": "^0.4.6", "eslint-plugin-security": "^1.7.1", "prettier": "^3.2.5", + "typedoc": "^0.25.13", "typescript": "^5.4.5", "vitest": "^1.4.0" }, diff --git a/tsconfig.base.json b/tsconfig.base.json index 38a620a3..0568030d 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -16,5 +16,5 @@ "allowSyntheticDefaultImports": true, "lib": ["DOM", "DOM.Iterable", "ESNext"], "types": ["node"] - } + }, } diff --git a/typedoc/landing-page.md b/typedoc/landing-page.md new file mode 100644 index 00000000..fa7c6a44 --- /dev/null +++ b/typedoc/landing-page.md @@ -0,0 +1,6 @@ +# Ably Chat JavaScript Client Library SDK API Reference + +The JavaScript Client Library SDK supports chat functionality over ably realtime. The JavaScript API references are generated from the [Ably Chat JavaScript Client Library SDK source code](https://github.com/ably-labs/ably-chat-js) using [TypeDoc](https://typedoc.org) and structured by classes. + +The Chat SDK is built on top of the Ably Realtime SDK and provides a higher-level API for building chat applications. It includes features such as entering/leaving conversations, sending messages, room reactions, presence, typing indicators, and more. + From 8d40f152efd342723bf05826a05e72ceae9e59b5 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Fri, 26 Apr 2024 15:03:44 +0100 Subject: [PATCH 02/11] Corrected IAM role to match infra definition of ably-chat-js --- .github/workflows/docks.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docks.yml b/.github/workflows/docks.yml index f9e71842..771325fe 100644 --- a/.github/workflows/docks.yml +++ b/.github/workflows/docks.yml @@ -31,7 +31,7 @@ jobs: 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-ably-js + role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-ably-chat-js role-session-name: "${{ github.run_id }}-${{ github.run_number }}" - name: Upload Documentation From e0daa823df2844dd209920da844dd13ce29c0f6d Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Fri, 26 Apr 2024 15:05:46 +0100 Subject: [PATCH 03/11] Added typedoc config --- typedoc.json | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 typedoc.json diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 00000000..5db6bdcf --- /dev/null +++ b/typedoc.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "entryPoints": ["src/index.ts"], + "out": "typedoc/generated", + "readme": "typedoc/landing-page.md", + "tsconfig": "tsconfig.base.json" +} From a49ef798c573a6b287ede0a007a612bb9632e2aa Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Fri, 26 Apr 2024 15:09:34 +0100 Subject: [PATCH 04/11] Added validation requirements. --- typedoc.json | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/typedoc.json b/typedoc.json index 5db6bdcf..de1537d4 100644 --- a/typedoc.json +++ b/typedoc.json @@ -3,5 +3,23 @@ "entryPoints": ["src/index.ts"], "out": "typedoc/generated", "readme": "typedoc/landing-page.md", - "tsconfig": "tsconfig.base.json" + "tsconfig": "tsconfig.base.json", + "treatWarningsAsErrors": false, + "includeVersion": true, + "validation": true, + "requiredToBeDocumented": [ + "Accessor", + "Class", + "Constructor", + "Enum", + "EnumMember", + "Function", + "Interface", + "Method", + "Parameter", + "Property", + "TypeAlias", + "Variable", + "Namespace" + ] } From e98d455253f32847f206e34e74d791dd42496565 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Fri, 26 Apr 2024 15:30:35 +0100 Subject: [PATCH 05/11] Set role to ably-labs --- .github/workflows/docks.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docks.yml b/.github/workflows/docks.yml index 771325fe..bf2087de 100644 --- a/.github/workflows/docks.yml +++ b/.github/workflows/docks.yml @@ -31,7 +31,7 @@ jobs: 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-ably-chat-js + role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-labs-sdk-builds-ably-chat-js role-session-name: "${{ github.run_id }}-${{ github.run_number }}" - name: Upload Documentation From 761e79550c4e211c4648a127c5b80c89534931a0 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Mon, 29 Apr 2024 09:45:56 +0100 Subject: [PATCH 06/11] Updated to new configure-aws-credentials@v2 action. Fixed JSON trailing comma --- .github/workflows/docks.yml | 2 +- tsconfig.base.json | 22 +++++++++++++++++----- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/.github/workflows/docks.yml b/.github/workflows/docks.yml index bf2087de..f79b2c3e 100644 --- a/.github/workflows/docks.yml +++ b/.github/workflows/docks.yml @@ -28,7 +28,7 @@ jobs: run: npm run docs - name: Configure AWS Credentials - uses: aws-actions/configure-aws-credentials@v1 + uses: aws-actions/configure-aws-credentials@v2 with: aws-region: eu-west-2 role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-labs-sdk-builds-ably-chat-js diff --git a/tsconfig.base.json b/tsconfig.base.json index 0568030d..57df29af 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -1,6 +1,12 @@ { - "include": ["./src/**/*.ts"], - "exclude": ["./src/**/*.test.tsx", "./src/**/*.test.ts", "./src/fakes/**/*.ts"], + "include": [ + "./src/**/*.ts" + ], + "exclude": [ + "./src/**/*.test.tsx", + "./src/**/*.test.ts", + "./src/fakes/**/*.ts" + ], "compilerOptions": { "target": "es6", "rootDir": "./src", @@ -14,7 +20,13 @@ "skipLibCheck": true, "allowJs": true, "allowSyntheticDefaultImports": true, - "lib": ["DOM", "DOM.Iterable", "ESNext"], - "types": ["node"] - }, + "lib": [ + "DOM", + "DOM.Iterable", + "ESNext" + ], + "types": [ + "node" + ] + } } From b0c59f4bcfcc157dc07855f5957e3c6715dd6b22 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Mon, 29 Apr 2024 10:05:09 +0100 Subject: [PATCH 07/11] Fixing the most ridiculous typo --- .github/workflows/{docks.yml => docs.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/workflows/{docks.yml => docs.yml} (100%) diff --git a/.github/workflows/docks.yml b/.github/workflows/docs.yml similarity index 100% rename from .github/workflows/docks.yml rename to .github/workflows/docs.yml From 82005a60f368fd09e8efb0aed9c46786c5fe21d0 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Mon, 29 Apr 2024 10:06:23 +0100 Subject: [PATCH 08/11] Updated landing-page.md --- typedoc/landing-page.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/typedoc/landing-page.md b/typedoc/landing-page.md index fa7c6a44..d7802cc8 100644 --- a/typedoc/landing-page.md +++ b/typedoc/landing-page.md @@ -1,6 +1,10 @@ # Ably Chat JavaScript Client Library SDK API Reference -The JavaScript Client Library SDK supports chat functionality over ably realtime. The JavaScript API references are generated from the [Ably Chat JavaScript Client Library SDK source code](https://github.com/ably-labs/ably-chat-js) using [TypeDoc](https://typedoc.org) and structured by classes. +The JavaScript Client Library SDK supports chat functionality over Ably. The JavaScript API references are generated +from the [Ably Chat JavaScript Client Library SDK source code](https://github.com/ably-labs/ably-chat-js) +using [TypeDoc](https://typedoc.org) and structured by classes. -The Chat SDK is built on top of the Ably Realtime SDK and provides a higher-level API for building chat applications. It includes features such as entering/leaving conversations, sending messages, room reactions, presence, typing indicators, and more. +The Chat SDK is built on top of the Ably Realtime SDK and provides a higher-level API for building chat applications. It +includes features such as entering/leaving conversations, sending messages, room reactions, presence, typing indicators, +and more. From a20f2f0907503de7ea2acc10c5c706c14bc0edaa Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Mon, 29 Apr 2024 10:23:14 +0100 Subject: [PATCH 09/11] Updated github perms --- .github/workflows/docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f79b2c3e..3470e860 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -13,6 +13,7 @@ jobs: permissions: deployments: write id-token: write + contents: read steps: - uses: actions/checkout@v3 From 0b460f6f4ee18995041c152008046fc5d745a326 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Mon, 29 Apr 2024 10:28:44 +0100 Subject: [PATCH 10/11] Updated to sdk-upload-action@v2 --- .github/workflows/docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3470e860..02bc901d 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -29,14 +29,14 @@ jobs: run: npm run docs - name: Configure AWS Credentials - uses: aws-actions/configure-aws-credentials@v2 + 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-labs-sdk-builds-ably-chat-js role-session-name: "${{ github.run_id }}-${{ github.run_number }}" - name: Upload Documentation - uses: ably/sdk-upload-action@v1 + uses: ably/sdk-upload-action@v2 with: sourcePath: typedoc/generated githubToken: ${{ secrets.GITHUB_TOKEN }} From a03c3bf88126ec74647679c7e0b40686be02c3e9 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Mon, 29 Apr 2024 10:29:51 +0100 Subject: [PATCH 11/11] Added docs action to npm --- package.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index a9e5b4a6..59e0a3c0 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,8 @@ "build": "npm run build:mjs && npm run build:cjs", "build:mjs": "tsc --project tsconfig.mjs.json && cp package.mjs.json dist/mjs/package.json", "build:cjs": "tsc --project tsconfig.cjs.json && cp package.cjs.json dist/cjs/package.json", - "demo:reload": "npm run build && cd demo && npm i file:../" + "demo:reload": "npm run build && cd demo && npm i file:../", + "docs": "typedoc" }, "repository": { "type": "git",