Feature/documentation additions (#4645)

* Add a section on buffer management * Add version migration guides * Rename to "Usage" * Add missing images * Adjust index.md * Update dependencies.md * Additional usage instructions * Additional usage instructions * Add MPD patching and content steering
Dash-Industry-Forum · Dec 11, 2024 · a66859e · a66859e
1 parent c8b91fb
commit a66859e
Show file tree

Hide file tree

Showing 60 changed files with 1,415 additions and 663 deletions.
diff --git a/_config.yml b/_config.yml
@@ -32,6 +32,20 @@ aux_links:
   "dash.js on GitHub":
     - "//github.com/Dash-Industry-Forum/dash.js"
 
+nav_external_links:
+  - title: API documentation
+    url: https://cdn.dashjs.org/latest/jsdoc/index.html
+    hide_icon: false # set to true to hide the external link icon - defaults to false
+    opens_in_new_tab: true # set to true to open this link in a new tab - defaults to false
+  - title: Sample Section
+    url: https://reference.dashif.org/dash.js/nightly/samples/index.html
+    hide_icon: false # set to true to hide the external link icon - defaults to false
+    opens_in_new_tab: true # set to true to open this link in a new tab - defaults to false
+  - title: Reference Client
+    url: https://reference.dashif.org/dash.js/nightly/samples/dash-if-reference-player/index.html
+    hide_icon: false # set to true to hide the external link icon - defaults to false
+    opens_in_new_tab: true # set to true to open this link in a new tab - defaults to false
+
 # Build settings
 theme: just-the-docs
 color_scheme: custom

diff --git a/assets/images/buffer-management.jpg b/assets/images/buffer-management.jpg
diff --git a/assets/images/lcevc/dependent-representations.png b/assets/images/lcevc/dependent-representations.png
diff --git a/assets/images/lcevc/enhancement-stream-processor.png b/assets/images/lcevc/enhancement-stream-processor.png
diff --git a/assets/images/mpd-patching.jpg b/assets/images/mpd-patching.jpg
diff --git a/assets/images/sources/buffer-management.drawio b/assets/images/sources/buffer-management.drawio
@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2024-12-09T10:37:44.925Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/20.8.16 Chrome/106.0.5249.199 Electron/21.4.0 Safari/537.36" etag="oOnJ_cB4Q3aLUmvlfR9g" version="20.8.16" type="device"><diagram name="Page-1" id="Zb0P8DDkofjZFAVFPaxz">zZddb5swFIZ/TS4nGQwOuWySdpP2oW6t1O3SwAGsGcyMaZL++hkwCQSyJhWLmpvg1/Yxfs6H8Qyv0u1HSfPkqwiBz2wUbmd4PbNtG80d/Vcpu0axbMsosWSh0Q7CA3sBIyKjliyEojdQCcEVy/tiILIMAtXTqJRi0x8WCd5fNacxDISHgPKh+sRClRiVuM6h4xOwOGmXtsii6UlpO9pspUhoKDYdCd/O8EoKoZqndLsCXuFrwTTz7k707t9MQqbOmZD+Ij//PPno/hvf/giKtZqT1Qdj5Zny0uw4l2UGodb8MopAmndXu5aIFGUWQmUTzfBykzAFDzkNqt6NDgKtJSrlumXpx4hxvhJcyHoujrwAgkDrhZLiN3R6fM913MqgeR+QCrYnN2rt8enIA5GCkjs9xExwkCFugs5emPam60GjJR3nYaNREzTx3vQBq34wZC+g7A4oN3AfxWeAfFLEPgIMZAwxAg953jSIXXIGYvuaiMkpxCyFNUS05GpSzqELXuiMcfZsHxMyDWfivbdQxgPOA6yQhTdV6dUtkUPWx9hn3sBrK6tdK1Sq/XS9TKvdMd7a0AuY1qFiQDgo5K9C7kB0Rxi2mgROFXvumx8Da1a4F0wvfLIcYfvIN4UoZQBmVreAHxmyrMUrljSnGNTAUu3o/b7f7vv5P3LsRj2K/HtJOVO7SRONILqw5mOJZq/nBFUGI5Gp7ilT//5TApJhAu6T8ioJ6J3phC8ii++ETCd1BkIeRWj0dEHu/OrOwENnOFc9dRYXVcNMZHBZNexXunNq43uvhsc+xO4bq+HA0JWLYXtD6fg+KGVNWePmVDMg+psDL339DU3i6ikXBVNMZIMY0Smh+oGhUzjWJ+c60Pb0RzheVonD9L3kxnSkLAyr6UsJBXuhfm0K1YvoDdcI3OXMXVe2SqUXrm9W1iB1TUx289xIUyQsPuHsTqyNFU/n8nzVzcNVqvHx4UqKb/8C</diagram></mxfile>
diff --git a/index.md b/index.md
@@ -51,6 +51,6 @@ The full [API Documentation](http://cdn.dashjs.org/latest/jsdoc/module-MediaPlay
 For help, join our [Slack channel](https://dashif-slack.azurewebsites.net),
 our [email list](https://groups.google.com/d/forum/dashjs) and read the documentation on this website.
 
-### License
+# License
 
 dash.js is released under [BSD license](https://github.com/Dash-Industry-Forum/dash.js/blob/development/LICENSE.md)
diff --git a/pages/advanced/buffer-management.md b/pages/advanced/buffer-management.md
diff --git a/pages/advanced/index.md b/pages/advanced/index.md
diff --git a/pages/advanced/mpd-patching.md b/pages/advanced/mpd-patching.md
diff --git a/pages/advanced/subtitles-and-captions/index.md b/pages/advanced/subtitles-and-captions/index.md
diff --git a/pages/advanced/subtitles-and-captions/subtitle-handling.md b/pages/advanced/subtitles-and-captions/subtitle-handling.md
diff --git a/pages/developers/architecture.md b/pages/developers/architecture.md
@@ -3,3 +3,6 @@ layout: default
 title: Architecture
 parent: Developers
 ---
+
+# Architecture
+To be done
diff --git a/pages/developers/debugging.md b/pages/developers/debugging.md
@@ -3,3 +3,7 @@ layout: default
 title: Debugging
 parent: Developers
 ---
+
+# Debugging
+
+To be done
diff --git a/pages/developers/dependencies.md b/pages/developers/dependencies.md
@@ -26,37 +26,44 @@ development. The dependencies are listed in `package.json` and are installed whe
 
 ## Dev Dependencies
 
-| Package                       | Usage                                                                                                   |
-|:------------------------------|:--------------------------------------------------------------------------------------------------------|
-| `@babel/core`                 | Required by babel-loader for Webpack and transpiling to ES5                                             |
-| `@babel/eslint-parser`        | Allows ESLint to run on source code that is transformed by Babel.                                       |
-| `@babel/preset-env`           | Required by babel-loader for Webpack and transpiling to ES5                                             |
-| `babel-loader`                | Used for transpiling JavaScript by Webpack                                                              |
-| `chai`                        | Assertion library used by the Karma testing framework                                                   |
-| `chai-spies`                  | Addon plugin for the chai assertion library. It provides the most basic function spy ability and tests. |
-| `clean-jsdoc-theme`           | Clean and fully responsive theme to generate the JSDoc.                                                 |
-| `eslint`                      | Tool for identifying and reporting on patterns found in JavaScript code                                 |
-| `eslint-webpack-plugin`       | Webpack plugin to run ESLint                                                                            |
-| `karma`                       | Testrunner for unit and functional tests                                                                | |
-| `karma-browserstack-launcher` | Launch tests on Browserstack via Karma                                                                  |
-| `karma-chai`                  | Use asserts like "expect" from the chai library                                                         |
-| `karma-chrome-launcher`       | Launches Chrome for unit and functional tests                                                           |
-| `karma-coverage`              | Creates coverage report for unit tests                                                                  |
-| `karma-firefox-launcher`      | Launches Firefox for unit and functional tests                                                          |
-| `karma-htmlfile-reporter`     | Creates an HTML test report for functional tests                                                        |
-| `karma-junit-reporter`        | Creates a JUnit test report for unit and functional test                                                |
-| `karma-mocha`                 | Testframework for unit and functional tests                                                             |
-| `karma-mocha-reporter`        | Mocha like test output for unit tests                                                                   |
-| `karma-webdriver-launche`     | Run Karma tests using Webdriver. Required for test execution via Selenium                               |
-| `karma-webpack`               | Webpack bundler for Karma testcases.                                                                    |
-| `mocha`                       | JavaScript test framework for our unit and functional tests                                             |
-| `rimraf`                      | Dependency to remove `dist` folder before building dash.js                                              |
-| `sinon`                       | Standalone and test framework agnostic JavaScript test spies, stubs and mocks                           |
-| `stream-browserify`           | The stream module from node core, for browsers                                                          |
-| `string-replace-loader`       | Used to perform text replacements when building with webpack                                            |
-| `typescript`                  | TypeScript adds optional types to JavaScript                                                            |
-| `webpack`                     | Module bundler used to create the dash.js builds                                                        |
-| `webpack-cli`                 | Allows setup of webpack custom configuration                                                            |
-| `webpack-dev-server`          | Development server that uses webpack for bundling                                                       |
-| `webpack-merge`               | Used to merge Webpack configuration files                                                               |
-| `yargs`                       | Parses arguments provided via command line for execution of functional tests                            |
+| Package                                      | Usage                                                                                                   |
+|:---------------------------------------------|:--------------------------------------------------------------------------------------------------------|
+| `@babel/core`                                | Required by babel-loader for Webpack and transpiling to ES5                                             |
+| `@babel/eslint-parser`                       | Allows ESLint to run on source code that is transformed by Babel.                                       |
+| `@babel/plugin-transform-parameters`         | Transforms ES2015 parameters to ES5 as part of the Webpack process.                                     |
+| `@babel/plugin-transform-runtime`            | A plugin that enables the re-use of Babel's injected helper code to save on codesize.                   |
+| `@babel/preset-env`                          | Required by babel-loader for Webpack and transpiling to ES5                                             |
+| `@chiragrupani/karma-chromium-edge-launcher` | An Edge launcher for Karma that is used for executing function tests in the Edge browser                |
+| `@eslint/js`                                 | ESLint JavaScript language implementation                                                               |
+| `babel-loader`                               | Used for transpiling JavaScript by Webpack                                                              |
+| `chai`                                       | Assertion library used by the Karma testing framework                                                   |
+| `chai-spies`                                 | Addon plugin for the chai assertion library. It provides the most basic function spy ability and tests. |
+| `clean-jsdoc-theme`                          | Clean and fully responsive theme to generate the JSDoc.                                                 |
+| `core-js`                                    | Modular standard library for JavaScript to polyfill ECMAScript features.                                |
+| `eslint`                                     | Tool for identifying and reporting on patterns found in JavaScript code                                 |
+| `eslint-webpack-plugin`                      | Webpack plugin to run ESLint                                                                            |
+| `globals`                                    | Global identifiers from different JavaScript environments                                               |
+| `karma`                                      | Testrunner for unit and functional tests                                                                | |
+| `karma-browserstack-launcher`                | Launch tests on Browserstack via Karma                                                                  |
+| `karma-chai`                                 | Use asserts like "expect" from the chai library                                                         |
+| `karma-chrome-launcher`                      | Launches Chrome for unit and functional tests                                                           |
+| `karma-coverage`                             | Creates coverage report for unit tests                                                                  |
+| `karma-firefox-launcher`                     | Launches Firefox for unit and functional tests                                                          |
+| `karma-htmlfile-reporter`                    | Creates an HTML test report for functional tests                                                        |
+| `karma-junit-reporter`                       | Creates a JUnit test report for unit and functional test                                                |
+| `karma-mocha`                                | Testframework for unit and functional tests                                                             |
+| `karma-mocha-reporter`                       | Mocha like test output for unit tests                                                                   |
+| `karma-webdriver-launcher`                   | Run Karma tests using Webdriver. Required for test execution via Selenium                               |
+| `karma-webpack`                              | Webpack bundler for Karma testcases.                                                                    |
+| `mocha`                                      | JavaScript test framework for our unit and functional tests                                             |
+| `rimraf`                                     | Dependency to remove `dist` folder before building dash.js                                              |
+| `sinon`                                      | Standalone and test framework agnostic JavaScript test spies, stubs and mocks                           |
+| `stream-browserify`                          | The stream module from node core, for browsers                                                          |
+| `string-replace-loader`                      | Used to perform text replacements when building with webpack                                            |
+| `timers-browserify`                          | Adds support for the timers module to browserify.                                                       |
+| `typescript`                                 | TypeScript adds optional types to JavaScript                                                            |
+| `webpack`                                    | Module bundler used to create the dash.js builds                                                        |
+| `webpack-cli`                                | Allows setup of webpack custom configuration                                                            |
+| `webpack-dev-server`                         | Development server that uses webpack for bundling                                                       |
+| `webpack-merge`                              | Used to merge Webpack configuration files                                                               |
+| `yargs`                                      | Parses arguments provided via command line for execution of functional tests                            |
diff --git a/pages/developers/how-to-contribute.md b/pages/developers/how-to-contribute.md
@@ -1,8 +1,7 @@
 ---
-layout: default 
+layout: default
 title: How to contribute
 parent: Developers
-nav_order: 1
 ---
 
 <details  markdown="block">
@@ -22,11 +21,12 @@ contributions of any kind. Naturally this includes software contributions, but w
 testing, project coordination, marketing and more.
 
 For any kind of contribution your first port of call should be to join
-our [mailing list]( https://groups.google.com/d/forum/dashjs) and our [Slack channel](https://join.slack.com/t/dashif/shared_invite/zt-egme869x-JH~UPUuLoKJB26fw7wj3Gg). We welcome all contributions to the mailing list (
-including asking questions which demonstrate our documentation needs to be improved).
+our [mailing list]( https://groups.google.com/d/forum/dashjs) and
+our [Slack channel](https://join.slack.com/t/dashif/shared_invite/zt-egme869x-JH~UPUuLoKJB26fw7wj3Gg). We welcome all
+contributions (including asking questions which demonstrate our documentation needs to be improved).
 
 The dash.js project serves as the reference player for the DASH Industry Forum. Respecting this, if you wish to
-contribute features or behavior which are non-conforming with the [interop guidelines](https://dashif.org/guidelines/),
+contribute features or behavior which are non-conforming with the [interop guidelines](https://dashif.org/guidelines/iop-v5/),
 then that feature must be explicitly enabled behind a compatibility flag.
 
 ## Submitting and managing Issues
@@ -84,16 +84,14 @@ contribute a fix yourself (or have someone else create a fix on your behalf).
 
 1. Before starting work on a new feature, enhancement or fix, ask the group if anyone else is already working on the
    same task. This will avoid duplication of effort.
-1. Read and understand the wiki sections
-   on [Developer Getting Started Guide](https://github.com/Dash-Industry-Forum/dash.js/wiki/Developer-Getting-Started-Guide)
-   and [JSLint compliance](https://github.com/Dash-Industry-Forum/dash.js/wiki/JSLint-Compliance).
 1. Read and understand the project's [Branching Strategy](http://nvie.com/posts/a-successful-git-branching-model/).
 1. Fork the repository and setup a new branch to work in.
 1. In each of your files, include the required BSD-3 header
    available [here](https://dashif.org/docs/dash.js.license-header.May2013.txt). Be sure to replace the placeholder
    text "YOUR_COMPANY_NAME_HERE" with the name of your company before adding it to the header.
 1. Add or modify unit tests for any new or modified functionality in your patch.
-1. Run `npm run build` before you commit so that you may catch test failures, lint issues, or syntax errors. Pull requests that
+1. Run `npm run build` before you commit so that you may catch test failures, lint issues, or syntax errors. Pull
+   requests that
    do not compile or pass linter checks or pass all unit tests will not be accepted.
 1. If you are submitting code as an individual or on behalf of a company who is _not a member_ of the
    DASH [Industry Forum](http://dashif.org/members), then download, sign, scan and email back to the email list

diff --git a/pages/developers/index.md b/pages/developers/index.md
@@ -4,3 +4,10 @@ title: Developers
 nav_order: 4
 has_children: true
 ---
+
+# Developers
+
+This section contains useful information for developers. Some parts are still work in progress and will be added over
+time. If you like to contribute to the dash.js project checkout out the [How to contribute](how-to-contribute/index.html)
+section.
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		<mxfile host="Electron" modified="2024-12-09T10:37:44.925Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/20.8.16 Chrome/106.0.5249.199 Electron/21.4.0 Safari/537.36" etag="oOnJ_cB4Q3aLUmvlfR9g" version="20.8.16" type="device"><diagram name="Page-1" id="Zb0P8DDkofjZFAVFPaxz">zZddb5swFIZ/TS4nGQwOuWySdpP2oW6t1O3SwAGsGcyMaZL++hkwCQSyJhWLmpvg1/Yxfs6H8Qyv0u1HSfPkqwiBz2wUbmd4PbNtG80d/Vcpu0axbMsosWSh0Q7CA3sBIyKjliyEojdQCcEVy/tiILIMAtXTqJRi0x8WCd5fNacxDISHgPKh+sRClRiVuM6h4xOwOGmXtsii6UlpO9pspUhoKDYdCd/O8EoKoZqndLsCXuFrwTTz7k707t9MQqbOmZD+Ij//PPno/hvf/giKtZqT1Qdj5Zny0uw4l2UGodb8MopAmndXu5aIFGUWQmUTzfBykzAFDzkNqt6NDgKtJSrlumXpx4hxvhJcyHoujrwAgkDrhZLiN3R6fM913MqgeR+QCrYnN2rt8enIA5GCkjs9xExwkCFugs5emPam60GjJR3nYaNREzTx3vQBq34wZC+g7A4oN3AfxWeAfFLEPgIMZAwxAg953jSIXXIGYvuaiMkpxCyFNUS05GpSzqELXuiMcfZsHxMyDWfivbdQxgPOA6yQhTdV6dUtkUPWx9hn3sBrK6tdK1Sq/XS9TKvdMd7a0AuY1qFiQDgo5K9C7kB0Rxi2mgROFXvumx8Da1a4F0wvfLIcYfvIN4UoZQBmVreAHxmyrMUrljSnGNTAUu3o/b7f7vv5P3LsRj2K/HtJOVO7SRONILqw5mOJZq/nBFUGI5Gp7ilT//5TApJhAu6T8ioJ6J3phC8ii++ETCd1BkIeRWj0dEHu/OrOwENnOFc9dRYXVcNMZHBZNexXunNq43uvhsc+xO4bq+HA0JWLYXtD6fg+KGVNWePmVDMg+psDL339DU3i6ikXBVNMZIMY0Smh+oGhUzjWJ+c60Pb0RzheVonD9L3kxnSkLAyr6UsJBXuhfm0K1YvoDdcI3OXMXVe2SqUXrm9W1iB1TUx289xIUyQsPuHsTqyNFU/n8nzVzcNVqvHx4UqKb/8C</diagram></mxfile>