From c30b812444645df81a5634f3cc23a4aadc556138 Mon Sep 17 00:00:00 2001 From: Jianjun Zhu Date: Thu, 11 Jan 2018 18:01:19 +0800 Subject: [PATCH] Add doc task to Grunt and update documentation. Docs will be generated in dist/doc. Change-Id: I27bb726f194433461a7dabb8b07c7f498c1c5250 Reviewed-on: https://git-amr-3.devtools.intel.com/gerrit/156252 Reviewed-by: Qiu, Jianlin Tested-by: Qiu, Jianlin --- docs/jsdoc/config.json | 7 +- docs/mdfiles/index.md | 503 +++++-------------------------------- docs/thirdpartylicense.txt | 12 + package.json | 4 +- scripts/Gruntfile.js | 16 +- 5 files changed, 100 insertions(+), 442 deletions(-) diff --git a/docs/jsdoc/config.json b/docs/jsdoc/config.json index aed002d1..f87131a7 100644 --- a/docs/jsdoc/config.json +++ b/docs/jsdoc/config.json @@ -2,8 +2,8 @@ "plugins": ["plugins/markdown"], "recurseDepth": 10, "source": { - "include": "../src/sdk", - "exclude": ["../src/sdk/icsREST", "../src/sdk/nuve", "../src/sdk/ui"], + "include": "src/sdk", + "exclude": ["src/sdk/rest", "src/sdk/nuve", "src/sdk/ui"], "excludePattern": "w*.legacy.*" }, "sourceType": "module", @@ -25,7 +25,8 @@ "linenums": true, "collapseSymbols": false, "inverseNav": true, - "highlightTutorialCode": true + "highlightTutorialCode": true, + "search": false }, "markdown": { "parser": "gfm", diff --git a/docs/mdfiles/index.md b/docs/mdfiles/index.md index 819984d3..f59197bb 100644 --- a/docs/mdfiles/index.md +++ b/docs/mdfiles/index.md @@ -1,121 +1,50 @@ Intel CS for WebRTC Client SDK for JavaScript ------------------ -# 1 Introduction {#section1} -The Intel CS for WebRTC Client SDK for JavaScript provides tools to help you develop Web applications. The SDK is distributed in the `CS_WebRTC_Client_SDK_JavaScript.<ver>.zip` release package. The SDK consists of client-side and server-side APIs, as well as sample Web applications: - - - Client-side APIs: Manage how to act with the peer client, room, and stream. - - Server-side APIs: Manage how to create a token, room, and service. - -The following table lists the basic JavaScript objects provided in the JavaScript SDK: - -@htmlonly - - - - - - - - - - - - - - - - - - -
Table 1: Basic JavaScript objects
JavaScript objectDescription
adapter.jsAn adapter to interop between different browsers.
woogeen.sdk.jsIntel CS for WebRTC client SDK for JavaScript.
-@endhtmlonly +# 1 Introduction +The Intel CS for WebRTC Client SDK for JavaScript provides tools to help you develop Web applications. The SDK is distributed in the `CS_WebRTC_Client_SDK_JavaScript..zip` release package. Refer to the SDK release notes for the latest information on the SDK release package, including features, supported browsers, bug fixes, and known issues. -Please include adaper.js before woogeen.sdk.js in HTML files. adapter.js is an open source project hosted on [Github](https://github.com/webrtc/adapter). The revision we depend on is d6e8b1a45add33f382fed872f32908ea225a1996. +Please include `adaper.js` before `ics.js` in HTML files. `adapter.js` is an open source project hosted on [Github](https://github.com/webrtc/adapter). The revision we depend on is `d6e8b1a45add33f382fed872f32908ea225a1996`. -If you want to use conference SDK, please also include socket.io.js before woogeen.sdk.js. +If you want to use conference SDK, please also include `socket.io.js` before `ics.js`. + +# 2 Browser requirement -# 2 Browser requirement {#section2} The Intel CS for WebRTC Client SDK for JavaScript has been tested on the following browsers and operating systems: -@htmlonly - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Table 2: Browser requirements
BrowserOS
Conference ModeWindows*Ubuntu*macOS*
Chrome* 62√√√
Firefox* 56√√√
Safari* 11√
Microsoft Edge* 40.15063.674.0√
P2P ModeWindows*Ubuntu*macOS*
Chrome* 62√√√
Firefox* 56√√√
Safari* 11√
-@endhtmlonly +Conference Mode: + +| | Windows* | Ubuntu* | macOS* | +| ------------------------------- | -------- | ------- |------- | +| Chrome* 62 | √ | √ | √ | +| Firefox* 56 | √ | √ | √ | +| Safari* 11 | | | √ | +| Microsoft Edge* 40.15063.674.0 | √ | | | | + +*Table 1: Browser requirements for Conference Mode* + + +P2P Mode: + +| | Windows* | Ubuntu* | macOS* | +| ------------------------------- | -------- | ------- |------- | +| Chrome* 62 | √ | √ | √ | +| Firefox* 56 | √ | √ | √ | +| Safari* 11 | | | √ | + +*Table 2: Browser requirements for P2P Mode* + Different browsers may have different supported codec list. Currently, Edge browser only supports H.264 and OPUS, and there is some video codec capability limitation, such as no FIR support in Edge. Safari support is limited. Not all functions work in Safari. -In P2P mode, only one stream per direction can be published between Firefox and other clients. Also, unpublish is not available when one side is Firefox. +In P2P mode, only one stream per direction can be published between Firefox and other clients. -# 3 Screen sharing {#section3} +# 3 Screen sharing ## 3.1 Chrome We provide source code of a Chrome screen sharing extension sample. Developers should edit manifest.json and publish it to Chrome App Store to make it work for their products. After your extension is published, you will get an extension ID. This ID will be used when creating screen sharing stream. @@ -130,199 +59,47 @@ Screen sharing on Firefox requires following in `about:config`. Developers can help end users to make these changes by Firefox extension. -> **note:** End users need to visit your site with https if they want to use screen sharing. +> **Note:** End users need to visit your site with https if they want to use screen sharing. -# 4 NAT and firewall traversal {#section4} +# 4 NAT and firewall traversal Intel CS for WebRTC Client SDK for JavaScript fully supports NAT and firewall traversal with STUN / TURN / ICE. The Coturn TURN server from https://github.com/coturn/coturn can be one choice. -# 5 Peer-to-peer (P2P) mode{#section5} +# 5 Peer-to-peer (P2P) mode To enable P2P chat, copy and paste the following code into the head section of your HTML document: ~~~~~~{.js} - + ~~~~~~ If you're using customized signling channel, please replace `socket.io.js` and `sc.websocket.js` with your own signaling channel implementation. -## 5.1 P2P direct call chat {#section5_1} +## 5.1 P2P direct call chat Direct call chat refers to the discovery of another client by chatting with that user's ID. This is a synchronous call and requires that the two clients should be online on the signaling server. ~~~~~~{.js} ~~~~~~ -## 5.2 Customize signaling channel {#section5_2} +## 5.2 Customize signaling channel -Signaling channel is an implementation to transmit signaling data for creating a WebRTC session. Signaling channel for P2P sessions can be customized by writing your own `sc.*.js`. The default Socket.IO signaling channel has been provided in the release package with name `sc.websocket.js`. +Signaling channel is an implementation to transmit signaling data for creating a WebRTC session. Signaling channel for P2P sessions can be customized. You can pass your customized signaling channel to `P2PClient`'s constructor. The default Socket.IO signaling channel has been provided in the release package with a file named `sc.websocket.js`. -In the customized signaling channel, you need to implement `connect`, `disconnect` and `sendMessage`, invoke `onMessage` when a new message arrives, and invoke `onServerDisconnected` when the connection is lost. Then include your customized `sc.*.js` into the HTML page. +In the customized signaling channel, you need to implement `connect`, `disconnect` and `send`, invoke `onMessage` when a new message arrives, and invoke `onServerDisconnected` when the connection is lost. Then include your customized `sc.*.js` into the HTML page. -# 6 Conference mode {#section6} +# 6 Conference mode Conference mode is designed for applications with multiple participants. The JavaScript SDK includes a demo application for this. -## 6.1 Create a room from the server side {#section6_1} +## 6.1 Create a room from the server side Server-side APIs are run on Node.js, and act as a Node.js module: ~~~~~~{.js} -var Woogeen = require('nuve'); -~~~~~~ -The following sample code shows how to create a room and generate tokens so that clients can join the room. -~~~~~~ -var Woogeen = require('nuve'); -Woogeen.API.init(SERVICEID, SERVICEKEY, SERVICEHOST); -var room = {name: 'Demo Room'}; -var options = {}; -Woogeen.API.createRoom (room.name, options, function (resp) { - console.log (resp); - var myRoom = resp; - setTimeout (function () { - Woogeen.API.createToken(myRoom._id, 'Bob', 'User', function (token) { - console.log ('Token:', token); - }); - }, 100); -}, function (err) { - console.log ('Error:', err); -}, room); +// TODO: Samples need to be updated. ~~~~~~ -## 6.2 Join a conference from the client side {#section6_2} +## 6.2 Join a conference from the client side To initialize your HTML code, copy and paste the following code into the head section of your HTML document: ~~~~~~{.js} @@ -332,207 +109,61 @@ To initialize your HTML code, copy and paste the following code into the head se ~~~~~~ After a room and token are created, the token can then be sent to a client to join the conference using client-side APIs: ~~~~~~{.js} - +// TODO: Samples need to be updated. ~~~~~~ -# 7 JavaScript API quick start guide {#section7} -This section provides detailed examples for using the APIs provided in the SDK. Unless mentioned elsewhere, all APIs are under namespace `Woogeen`. +# 7 JavaScript API quick start guide +This section includes some examples for using the APIs provided in the SDK. -## 7.1 Objects {#section7_1} +## 7.1 Objects The following table describes the key objects provided in the JavaScript SDK. -@htmlonly - - - - - - - - - - - - - - - - - - - - - - - - - - -
Table 3 : JavaScript objects
JavaScript objectDescription
PeerClientSets up one-to-one WebRTC session for two clients. It provides methods to initialize or stop a audio/video call and P2P data transmission.
ConferenceClientProvides connection, local stream publication, and remote stream subscription for a audio/video conference. The conference client is created by the server side API. The conference client is retrieved by the client API with the access token for the connection.
SipClientProvides to initiate, accept, reject, hangup a SIP call. And also local stream publication, and remote stream subscription for a video or audio call.
StreamHandles the WebRTC (audio, video) stream, identifies the stream, and identifies the location where the stream should be displayed. There are two stream classes: LocalStream and RemoteStream.
-@endhtmlonly -## 7.2 Example: Get PeerClient {#section7_2} + +| JavaScript Object | Description | +| ---------------------------------| -------- | ------- |------- | +| Ics.Base.Stream | Handles the WebRTC (audio, video) stream, identifies the stream. There are two kinds of streams: LocalStream and RemoteStream. | +| Ics.Conference.ConferenceClient | Provides connection, local stream publication, and remote stream subscription for a audio/video conference. | +| Ics.P2P.P2PClient | Sets up a one-to-one WebRTC session for two endpoints. It provides methods to publish streams and send text messages to remote endpoint. | + +## 7.2 Example: Get PeerClient ~~~~~~{.js} ~~~~~~ -## 7.3 Example: Get ConferenceClient {#section7_3} +## 7.3 Example: Get ConferenceClient ~~~~~~{.js} ~~~~~~ -## 7.4 Example: Create LocalStream and receive RemoteStream {#section7_4} +## 7.4 Example: Create LocalStream and receive RemoteStream ~~~~~~{.js} ~~~~~~ -# 8 Events {#section8} - -The JavaScript objects (described earlier in this section) throw events using EventDispatchers, inlucluding {@link Woogeen.PeerClient PeerClient}, {@link Woogeen.ConferenceClient ConferenceClient}, {@link Woogeen.SipClient SipClient}, {@link Woogeen.RemoteStream RemoteStream}, etc. +# 8 Events -For more detailed events, please refer to the specific class description page. +The JavaScript objects (described earlier in this section) fires events using `Ics.Base.EventDispatchers`. For more detailed events, please refer to the specific class description page. -## 8.1 Example for conference:{#section8_1} +## 8.1 Example for conference ~~~~~~{.js} ~~~~~~ -## 8.2 Example for p2p:{#section8_2} +## 8.2 Example for p2p ~~~~~~{.js} ~~~~~~ -> **Note**: \* Other names and brands may be claimed as the property of others. +**Note:** \* Other names and brands may be claimed as the property of others. diff --git a/docs/thirdpartylicense.txt b/docs/thirdpartylicense.txt index 4a10cf9b..b80e2396 100644 --- a/docs/thirdpartylicense.txt +++ b/docs/thirdpartylicense.txt @@ -463,3 +463,15 @@ as published by Sam Hocevar. See below for more details. TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. You just DO WHAT THE FUCK YOU WANT TO. + + + DocStrap + ----------------------- + +DocStrap Copyright (c) 2012-2015 Terry Weiss & Contributors. All rights reserved. + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/package.json b/package.json index d5cddb86..de2a9b9d 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,9 @@ "grunt-contrib-jshint": "^1.1.0", "grunt-contrib-uglify-es": "git+https://github.com/gruntjs/grunt-contrib-uglify.git#ccb95a70cad6a4e9e902d3bd5d0e38a4de09a1e1", "grunt-eslint": "^19.0.0", - "grunt-string-replace": "~1.2.0" + "grunt-jsdoc": "^2.2.1", + "grunt-string-replace": "~1.2.0", + "ink-docstrap": "^1.3.2" }, "engines": { "node": ">=4.0" diff --git a/scripts/Gruntfile.js b/scripts/Gruntfile.js index 796485bd..978ca4c1 100644 --- a/scripts/Gruntfile.js +++ b/scripts/Gruntfile.js @@ -74,7 +74,7 @@ window.L = L;\n\ connect: { server: { options: { - base: '../', + base: '.', port: 7080, keepalive: true }, @@ -246,6 +246,17 @@ window.L = L;\n\ {src:['dist/**'],dest:'../'} ] } + }, + jsdoc : { + dist : { + src: ['src/sdk/', 'docs/mdfiles/index.md'], + options: { + destination: 'dist/doc', + template : 'node_modules/ink-docstrap/template', + configure : 'docs/jsdoc/config.json', + recurse: true + } + } } }); @@ -260,11 +271,12 @@ window.L = L;\n\ grunt.loadNpmTasks('grunt-eslint'); grunt.loadNpmTasks('grunt-browserify'); grunt.loadNpmTasks('grunt-contrib-connect'); + grunt.loadNpmTasks('grunt-jsdoc'); grunt.registerTask('build', ['eslint:src', 'concat:dist', 'concat:ui_dist', 'concat:nuve', 'concat:rest', 'jshint:dist', 'concat:merge', 'uglify:dist','copy:dist','string-replace','compress:dist']); grunt.registerTask('debug', ['concat:dist_debug', 'concat:ui_dist_debug', 'concat:nuve_debug', 'concat:icsREST_debug']); - grunt.registerTask('pack', ['browserify:dist', 'concat:rest', 'uglify:dist', 'copy:dist', 'compress:dist']); + grunt.registerTask('pack', ['browserify:dist', 'concat:rest', 'uglify:dist', 'copy:dist', 'compress:dist', 'jsdoc:dist']); grunt.registerTask('dev', ['browserify:dev', 'connect:server']); grunt.registerTask('default', ['pack']); };