Merge pull request #8 from DolbyIO/docs

Version 1.0.0

.github/workflows/build-documentation.yml

@@ -0,0 +1,48 @@
+name: Build Documentation
+
+on:
+    push:
+        branches:
+            - main
+
+jobs:
+    build-documentation:
+        runs-on: ubuntu-latest
+
+        # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+        permissions:
+            contents: read
+            pages: write # to deploy to Pages
+            id-token: write # to verify the deployment originates from an appropriate source
+
+        # Deploy to the github-pages environment
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+
+        steps:
+            - name: Checkout 🛎️
+              uses: actions/checkout@v4
+              with:
+                  persist-credentials: false
+
+            - name: Print NPM version 🌎
+              run: npm --version
+
+            - name: Install the dependencies 🧱
+              run: npm ci
+
+            - name: Build the documentation 🔨
+              run: npm run docs
+
+            - name: Setup GitHub Pages 🛠
+              uses: actions/configure-pages@v5
+
+            - name: Upload artifact ⬆️
+              uses: actions/upload-pages-artifact@v3
+              with:
+                  path: docs
+
+            - name: Deploy to GitHub Pages 🚀
+              id: deployment
+              uses: actions/deploy-pages@v4

.github/workflows/build-package.yml

@@ -17,7 +17,7 @@ jobs:
             - name: Print NPM version 🌎
               run: npm --version
             - name: Install the dependencies 🧱
-              run: npm install
+              run: npm ci
             - name: Test the package 🔧
               run: npm run test
             - name: Build the package 🔨

.github/workflows/codeql-analysis.yml

@@ -42,7 +42,7 @@ jobs:
 
             # Initializes the CodeQL tools for scanning.
             - name: Initialize CodeQL
-              uses: github/codeql-action/init@v2
+              uses: github/codeql-action/init@v3
               with:
                   languages: ${{ matrix.language }}
                   # If you wish to specify custom queries, you can do so here or in a config file.
@@ -55,7 +55,7 @@ jobs:
             # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
             # If this step fails, then you should remove it and run the build manually (see below)
             - name: Autobuild
-              uses: github/codeql-action/autobuild@v2
+              uses: github/codeql-action/autobuild@v3
 
             # ℹ️ Command-line programs to run using the OS shell.
             # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -68,6 +68,6 @@ jobs:
             #   ./location_of_script_within_repo/buildscript.sh
 
             - name: Perform CodeQL Analysis
-              uses: github/codeql-action/analyze@v2
+              uses: github/codeql-action/analyze@v3
               with:
                   category: '/language:${{matrix.language}}'

.github/workflows/publish-package.yml

@@ -16,7 +16,7 @@ jobs:
             - name: Print NPM version 🌎
               run: npm --version
             - name: Install the dependencies 🧱
-              run: npm install
+              run: npm ci
             - name: Test the package 🔧
               run: npm run test
             - name: Build the package 🔨

.gitignore

@@ -121,3 +121,4 @@ dist
 
 /.idea
 
+docs/

.prettierignore

@@ -1,3 +1,4 @@
 coverage
 dist
+docs
 node_modules

README.md

@@ -1,4 +1,5 @@
 [![Build Package](https://github.com/DolbyIO/web-webrtc-stats/actions/workflows/build-package.yml/badge.svg)](https://github.com/DolbyIO/web-webrtc-stats/actions/workflows/build-package.yml)
+[![Build Documentation](https://github.com/DolbyIO/web-webrtc-stats/actions/workflows/build-documentation.yml/badge.svg)](https://github.com/DolbyIO/web-webrtc-stats/actions/workflows/build-documentation.yml)
 [![Publish Package](https://github.com/DolbyIO/web-webrtc-stats/actions/workflows/publish-package.yml/badge.svg)](https://github.com/DolbyIO/web-webrtc-stats/actions/workflows/publish-package.yml)
 [![npm](https://img.shields.io/npm/v/@dolbyio/webrtc-stats)](https://www.npmjs.com/package/@dolbyio/webrtc-stats)
 [![License](https://img.shields.io/github/license/DolbyIO/web-webrtc-stats)](LICENSE)
@@ -9,43 +10,25 @@ This project is a library to use to parse WebRTC statistics.
 
 ## Install this project
 
-Run the npm command to install the package `@dolbyio/webrtc-stats` into your project:
+Run the following npm command to install the package `@dolbyio/webrtc-stats` into your project:
 
 ```bash
-npm install @dolbyio/webrtc-stats --save
+npm install @dolbyio/webrtc-stats
 ```
 
 ## Use the library
 
 ### Collection
 
-A `WebRTCStats` object needs to be created to start a WebRTC statistics collection. It requires some settings to configure how you want the collection to work.
-
-```js
-interface WebRTCStatsOptions {
-    /**
-     * Function that will be called to retrieve the WebRTC statistics.
-     * @returns a {@link RTCStatsReport} object through a {@link Promise}.
-     */
-    getStats: () => Promise<RTCStatsReport>;
-
-    /**
-     * Interval, in milliseconds, at which to collect the WebRTC statistics.
-     * Default is 1,000 ms (1 second).
-     */
-    getStatsInterval?: number;
-
-    /**
-     * Include the raw statistics in the `stats` event.
-     * Default is `false`.
-     */
-    includeRawStats?: boolean;
-}
+A `WebRTCStats` object needs to be created to start a WebRTC statistics collection. It requires some settings to configure how you want the collection to work. First, import the `WebRTCStats` definition.
+
+```ts
+import { WebRTCStats } from '@dolbyio/webrtc-stats';
 ```
 
-Create the collection object.
+Create the collection object like this example:
 
-```js
+```ts
 const collection = new WebRTCStats({
     getStats: () => {
         // Get the raw WebRTC statistics from the web browser
@@ -57,42 +40,42 @@ const collection = new WebRTCStats({
 
 Start the collection with the `start()` function.
 
-```js
+```ts
 collection.start();
 ```
 
 Stop the collection with the `stop()` function.
 
-```js
+```ts
 collection.stop();
 ```
 
 ### Events
 
-After starting the collection, the `stats` event is triggered when the WebRTC statistics have been collected and parsed. The `event` object is of type [OnStats](src/types/WebRTCStats.ts).
+After starting the collection, the `stats` event is triggered when the WebRTC statistics have been collected and parsed.
+
+```ts
+import { OnStats } from '@dolbyio/webrtc-stats';
 
-```js
-collection.on('stats', (event) => {
+collection.on('stats', (event: OnStats) => {
     console.log(event);
 });
 ```
 
 The `error` event is triggered when an error happens during the collection or the parsing of the WebRTC statistics.
 
-```js
-collection.on('error', (error) => {
-    console.error(error);
+```ts
+collection.on('error', (reason: string) => {
+    console.error(reason);
 });
 ```
 
-### Examples
-
-#### Dolby.io Real-time Streaming APIs
+### Example
 
-Example on how to start a statistics collection from the [Dolby.io Real-time Streaming APIs](https://docs.dolby.io/streaming-apis/docs).
+Example on how to start a statistics collection from the [Dolby Millicast](https://docs.dolby.io/streaming-apis/docs) SDK.
 
-```js
-import WebRTCStats from '@dolbyio/webrtc-stats';
+```ts
+import { WebRTCStats, OnStats } from '@dolbyio/webrtc-stats';
 import { Director, Publish } from '@millicast/sdk';
 
 const PUBLISHER_TOKEN = '';
@@ -106,7 +89,7 @@ const tokenGenerator = () =>
 
 const publisher = new Publish(STREAM_NAME, tokenGenerator);
 
-// Publish the stream
+// HERE: Publish a stream to Dolby Millicast
 
 const collection = new WebRTCStats({
     getStatsInterval: 1000,
@@ -116,48 +99,24 @@ const collection = new WebRTCStats({
 });
 
 // The stats event is triggered after each interval has elapsed
-collection.on('stats', (event) => {
-    // Triggered when the statistics have been parsed
+collection.on('stats', (event: OnStats) => {
     console.log(event);
 });
 
 // Start the statistics collection
 collection.start();
 ```
 
-#### Dolby.io Communications APIs
+## Logs
 
-Example on how to start a statistics collection from the [Dolby.io Communications APIs](https://docs.dolby.io/communications-apis/docs).
+You can also print the logs in the console and select the log level by using the following code.
 
-```js
-import WebRTCStats from '@dolbyio/webrtc-stats';
-import VoxeetSdk from '@voxeet/voxeet-web-sdk';
-
-const collection = new WebRTCStats({
-    getStatsInterval: 1000,
-    getStats: async () => {
-        // See: https://docs.dolby.io/communications-apis/docs/js-client-sdk-conferenceservice#localstats
-        const webRTCStats = await VoxeetSDK.conference.localStats();
-
-        // Convert the WebRTCStats object to RTCStatsReport
-        const values = Array.from(webRTCStats.values())[0];
-        const map = new Map();
-        for (let i = 0; i < values.length; i++) {
-            const element = values[i];
-            map.set(element.id, element);
-        }
-        return map;
-    },
-});
+```ts
+import { Logger } from '@dolbyio/webrtc-stats';
 
-// The stats event is triggered after each interval has elapsed
-collection.on('stats', (event) => {
-    // Triggered when the statistics have been parsed
-    console.log(event);
+Logger.useDefaults({
+    defaultLevel: Logger.TRACE,
 });
-
-// Start the statistics collection
-collection.start();
 ```
 
 ## How to
@@ -173,3 +132,16 @@ Create distribution package:
 ```bash
 npm run build
 ```
+
+The documentation is built on [TypeDoc](https://typedoc.org), to generate the doc, run the following command. You will find the HTML files in the `docs` folder.
+
+```bash
+npm run docs
+```
+
+## Related Projects
+
+-   [Millicast SDK](https://github.com/millicast/millicast-sdk)
+-   [js-logger](https://github.com/jonnyreeves/js-logger)
+-   [TypeDoc](https://typedoc.org)
+-   [Jest](https://jestjs.io/)