README to documentation synchro

apivideo · Nov 21, 2023 · 80f1748 · 80f1748
1 parent d7569ca
commit 80f1748
Show file tree

Hide file tree

Showing 2 changed files with 89 additions and 48 deletions.
diff --git a/.github/workflows/create-documentation-pr.yml b/.github/workflows/create-documentation-pr.yml
@@ -0,0 +1,27 @@
+name: Create documentation PR
+on:
+  # Trigger the workflow on pull requests targeting the main branch
+  pull_request:
+    types: [assigned, unassigned, opened, reopened, synchronize, edited, labeled, unlabeled, edited, closed]
+    branches:
+      - main
+
+jobs:
+  create_documentation_pr:
+    if: github.event.action != 'closed'
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out current repository code
+        uses: actions/checkout@v2
+
+      - name: Create the documentation pull request
+        uses: apivideo/api.video-create-readme-file-pull-request-action@main
+        with: 
+          source-file-path: "README.md"
+          destination-repository: apivideo/api.video-documentation
+          destination-path: sdks/vod
+          destination-filename: apivideo-typescript-uploader.md
+          pat: "${{ secrets.PAT }}"
+
diff --git a/README.md b/README.md
@@ -1,3 +1,4 @@
+<!--<documentation_excluded>-->
 [![badge](https://img.shields.io/twitter/follow/api_video?style=social)](https://twitter.com/intent/follow?screen_name=api_video) &nbsp; [![badge](https://img.shields.io/github/stars/apivideo/api.video-typescript-uploader?style=social)](https://github.com/apivideo/api.video-typescript-uploader) &nbsp; [![badge](https://img.shields.io/discourse/topics?server=https%3A%2F%2Fcommunity.api.video)](https://community.api.video)
 ![](https://github.com/apivideo/.github/blob/main/assets/apivideo_banner.png)
 <h1 align="center">api.video typescript video uploader</h1>
@@ -7,7 +8,7 @@
 
 [api.video](https://api.video) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app.
 
-# Table of contents
+## Table of contents
 
 - [Table of contents](#table-of-contents)
 - [Project description](#project-description)
@@ -17,7 +18,7 @@
     - [Installation method #2: typescript](#installation-method-2-typescript)
     - [Simple include in a javascript project](#simple-include-in-a-javascript-project)
 - [Documentation - Standard upload](#documentation---standard-upload)
-  - [Instanciation](#instanciation)
+  - [Instantiation](#instantiation)
     - [Options](#options)
       - [Using a delegated upload token (recommended):](#using-a-delegated-upload-token-recommended)
       - [Using an access token (discouraged):](#using-an-access-token-discouraged)
@@ -30,7 +31,7 @@
     - [`cancel()`](#cancel)
     - [`onPlayable()`](#onplayable)
 - [Documentation - Progressive upload](#documentation---progressive-upload)
-  - [Instanciation](#instanciation-1)
+  - [Instantiation](#instantiation-1)
     - [Options](#options-1)
       - [Using a delegated upload token (recommended):](#using-a-delegated-upload-token-recommended-1)
       - [Using an access token (discouraged):](#using-an-access-token-discouraged-1)
@@ -44,19 +45,32 @@
     - [`onPlayable()`](#onplayable-1)
 - [Static wrapper](#static-wrapper)
 
-# Project description
+<!--</documentation_excluded>-->
+<!--<documentation_only>
+---
+title: api.video TypeScript video uploader
+meta: 
+  description: The official api.video TypeScript video uploader for api.video. [api.video](https://api.video/) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app.
+---
+
+# api.video TypeScript video uploader
+
+[api.video](https://api.video/) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app.
+
+</documentation_only>-->
+## Project description
 
 Typescript library to upload videos to api.video using delegated upload token (or usual access token) from the front-end. 
 
 It allows you to upload videos in two ways:
 - standard upload: to send a whole video file in one go
 - progressive upload: to send a video file by chunks, without needing to know the final size of the video file
 
-# Getting started
+## Getting started
 
-## Installation
+### Installation
 
-### Installation method #1: requirejs
+#### Installation method #1: requirejs
 
 If you use requirejs you can add the library as a dependency to your project with 
 
@@ -82,7 +96,7 @@ var uploader = new ProgressiveUploader({
 }); 
 ```
 
-### Installation method #2: typescript
+#### Installation method #2: typescript
 
 If you use Typescript you can add the library as a dependency to your project with 
 
@@ -109,7 +123,7 @@ const uploader = new ProgressiveUploader({
 ```
 
 
-### Simple include in a javascript project
+#### Simple include in a javascript project
 
 Include the library in your HTML file like so:
 
@@ -136,17 +150,17 @@ Then, once the `window.onload` event has been trigered, create your player using
 </script>
 ```
 
-# Documentation - Standard upload
+## Documentation - Standard upload
 
-## Instanciation
+### Instantiation
 
-### Options 
+#### Options 
 
-The upload library is instanciated using an `options` object. Options to provide depend on the way you want to authenticate to the API: either using a delegated upload token (recommanded), or using a usual access token. 
+The upload library is instantiated using an `options` object. Options to provide depend on the way you want to authenticate to the API: either using a delegated upload token (recommanded), or using a usual access token. 
 
-#### Using a delegated upload token (recommended):
+##### Using a delegated upload token (recommended):
 
-Using delegated upload tokens for authentication is best options when uploading from the client side. To know more about delegated upload token, read the dedicated article on api.video's blog: [Delegated Uploads](https://api.video/blog/tutorials/delegated-uploads).
+Using delegated upload tokens for authentication is best options when uploading from the client side. To know more about delegated upload token, read the dedicated article on api.video's blog: [Delegated Uploads](https://api.video/blog/tutorials/delegated-uploads/).
 
 
 |                   Option name | Mandatory | Type   | Description             |
@@ -155,7 +169,7 @@ Using delegated upload tokens for authentication is best options when uploading
 |                       videoId | no        | string | id of an existing video |
 | _common options (see bellow)_ |           |        |                         |
 
-#### Using an access token (discouraged):
+##### Using an access token (discouraged):
 
 **Warning**: be aware that exposing your access token client-side can lead to huge security issues. Use this method only if you know what you're doing :).
 
@@ -168,7 +182,7 @@ Using delegated upload tokens for authentication is best options when uploading
 | _common options (see bellow)_ |           |        |                                                                                                                                                 |
 
 
-#### Using an API key (**strongly** discouraged):
+##### Using an API key (**strongly** discouraged):
 
 **Warning**: be aware that exposing your API key client-side can lead to huge security issues. Use this method only if you know what you're doing :).
 
@@ -180,7 +194,7 @@ Using delegated upload tokens for authentication is best options when uploading
 | _common options (see bellow)_ |           |        |                         |
 
 
-#### Common options
+##### Common options
 
 
 |   Option name    | Mandatory | Type                                                            | Description                                                                                                                              |
@@ -194,7 +208,7 @@ Using delegated upload tokens for authentication is best options when uploading
 | maxVideoDuration | no        | number                                                          | maximum duration allowed for the file (in seconds)                                                                                       |
 
 
-### Example
+#### Example
 
 ```javascript
     const uploader = new VideoUploader({
@@ -205,9 +219,9 @@ Using delegated upload tokens for authentication is best options when uploading
     });
 ```
 
-## Methods
+### Methods
 
-### `upload()`
+#### `upload()`
 
 The upload() method starts the upload. It takes no parameter. It returns a Promise that resolves once the file is uploaded. If an API call fails more than the specified number of retries, then the promise is rejected.
 On success, the promise embeds the `video` object returned by the API.
@@ -216,14 +230,14 @@ On fail, the promise embeds the status code & error message returned by the API.
 **Example**
 
 ```javascript
-    // ... uploader instanciation
+    // ... uploader instantiation
 
     uploader.upload()
         .then((video) => console.log(video))
         .catch((error) => console.log(error.status, error.message));
 ```
 
-### `onProgress()`
+#### `onProgress()`
 
 The onProgress() method let you defined an upload progress listener. It takes a callback function with one parameter: the onProgress events.
 An onProgress event contains the following attributes:
@@ -234,15 +248,15 @@ An onProgress event contains the following attributes:
 - currentChunk (number): index of the chunk being uploaded
 - currentChunkUploadedBytes (number): number of bytes uploaded for the current chunk
 
-### `cancel()`
+#### `cancel()`
 
 The cancel() method cancels the upload. It takes no parameter. 
 
 
 **Example**
 
 ```javascript
-    // ... uploader instanciation
+    // ... uploader instantiation
 
     uploader.onProgress((event) => {
         console.log(`total number of bytes uploaded for this upload: ${event.uploadedBytes}.`);
@@ -255,7 +269,7 @@ The cancel() method cancels the upload. It takes no parameter.
 ```
 
 
-### `onPlayable()`
+#### `onPlayable()`
 
 The onPlayable() method let you defined a listener that will be called when the video is playable. It takes a callback function with one parameter: the `video` object returned by the API.
 
@@ -265,7 +279,7 @@ The onPlayable() method let you defined a listener that will be called when the
     <div id="player-container"></div>
 
     <script>
-        // ... uploader instanciation
+        // ... uploader instantiation
     
         uploader.onPlayable((video) => {
             // the video is playable, we can display the player
@@ -274,18 +288,18 @@ The onPlayable() method let you defined a listener that will be called when the
     </script>
 ```
 
-# Documentation - Progressive upload
+## Documentation - Progressive upload
 
 
-## Instanciation
+### Instantiation
 
-### Options 
+#### Options 
 
-The progressive upload object is instanciated using an `options` object. Options to provide depend on the way you want to authenticate to the API: either using a delegated upload token (recommanded), or using a usual access token. 
+The progressive upload object is instantiated using an `options` object. Options to provide depend on the way you want to authenticate to the API: either using a delegated upload token (recommanded), or using a usual access token. 
 
-#### Using a delegated upload token (recommended):
+##### Using a delegated upload token (recommended):
 
-Using delegated upload tokens for authentication is best options when uploading from the client side. To know more about delegated upload token, read the dedicated article on api.video's blog: [Delegated Uploads](https://api.video/blog/tutorials/delegated-uploads).
+Using delegated upload tokens for authentication is best options when uploading from the client side. To know more about delegated upload token, read the dedicated article on api.video's blog: [Delegated Uploads](https://api.video/blog/tutorials/delegated-uploads/).
 
 
 |                   Option name | Mandatory | Type   | Description             |
@@ -294,7 +308,7 @@ Using delegated upload tokens for authentication is best options when uploading
 |                       videoId | no        | string | id of an existing video |
 | _common options (see bellow)_ |           |        |                         |
 
-#### Using an access token (discouraged):
+##### Using an access token (discouraged):
 
 **Warning**: be aware that exposing your access token client-side can lead to huge security issues. Use this method only if you know what you're doing :).
 
@@ -306,7 +320,7 @@ Using delegated upload tokens for authentication is best options when uploading
 | _common options (see bellow)_ |           |        |                         |
 
 
-#### Common options
+##### Common options
 
 
 |       Option name           | Mandatory | Type                                                            | Description                                                                                                                                            |
@@ -318,7 +332,7 @@ Using delegated upload tokens for authentication is best options when uploading
 | mergeSmallPartsBeforeUpload | no        | boolean                                                         | if false, parts smaller than 5MB will not be merged before upload, resulting in an error (default: true)                                               |
 
 
-### Example
+#### Example
 
 ```javascript
     const uploader = new ProgressiveUploader({
@@ -327,9 +341,9 @@ Using delegated upload tokens for authentication is best options when uploading
     });
 ```
 
-## Methods
+### Methods
 
-### `uploadPart(file: Blob)`
+#### `uploadPart(file: Blob)`
 
 The upload() method starts the upload. It takes no parameter. It returns a Promise that resolves once the file is uploaded. If an API call fails more than the specified number of retries, then the promise is rejected.
 On success, the promise embeds the `video` object returned by the API.
@@ -338,13 +352,13 @@ On fail, the promise embeds the status code & error message returned by the API.
 **Example**
 
 ```javascript
-    // ... uploader instanciation
+    // ... uploader instantiation
 
     uploader.uploadPart(blob)
         .catch((error) => console.log(error.status, error.message));
 ```
 
-### `uploadLastPart(file: Blob)`
+#### `uploadLastPart(file: Blob)`
 
 The upload() method starts the upload. It takes no parameter. It returns a Promise that resolves once the file is uploaded. If an API call fails more than the specified number of retries, then the promise is rejected.
 On success, the promise embeds the `video` object returned by the API.
@@ -353,14 +367,14 @@ On fail, the promise embeds the status code & error message returned by the API.
 **Example**
 
 ```javascript
-    // ... uploader instanciation
+    // ... uploader instantiation
 
     uploader.uploadLastPart(blob)
         .then((video) => console.log(video))
         .catch((error) => console.log(error.status, error.message));
 ```
 
-### `onProgress()`
+#### `onProgress()`
 
 The onProgress() method let you defined an upload progress listener. It takes a callback function with one parameter: the onProgress events.
 An onProgress event contains the following attributes:
@@ -371,7 +385,7 @@ An onProgress event contains the following attributes:
 **Example**
 
 ```javascript
-    // ... uploader instanciation
+    // ... uploader instantiation
 
     uploader.onProgress((event) => {
         console.log(`total number of bytes uploaded for this upload: ${event.uploadedBytes}.`);
@@ -380,11 +394,11 @@ An onProgress event contains the following attributes:
     });
 ```
 
-### `cancel()`
+#### `cancel()`
 
 The cancel() method cancels the upload. It takes no parameter. 
 
-### `onPlayable()`
+#### `onPlayable()`
 
 The onPlayable() method let you defined a listener that will be called when the video is playable. It takes a callback function with one parameter: the `video` object returned by the API.
 
@@ -394,7 +408,7 @@ The onPlayable() method let you defined a listener that will be called when the
     <div id="player-container"></div>
 
     <script>
-        // ... uploader instanciation
+        // ... uploader instantiation
     
         uploader.onPlayable((video) => {
             // the video is playable, we can display the player
@@ -404,6 +418,6 @@ The onPlayable() method let you defined a listener that will be called when the
 ```
 
 
-# Static wrapper
+## Static wrapper
 
-For situations where managing object instances is impractical, consider using the [UploaderStaticWrapper](./doc/UploaderStaticWrapper.md) class, which offers static method equivalents for all functionalities.
+For situations where managing object instances is impractical, consider using the [UploaderStaticWrapper](https://github.com/apivideo/api.video-typescript-uploader/blob/main/doc/UploaderStaticWrapper.md) class, which offers static method equivalents for all functionalities.