Docs: Update to jekyll-theme-amethyst 0.4.1 (TOC, gh-pages deploy)

.editorconfig

@@ -14,6 +14,6 @@ trim_trailing_whitespace = false
 [test/integration/nyc.js]
 trim_trailing_whitespace = false
 
-[*.{yml,md}]
+[*.{yml,yaml,md}]
 indent_style = space
 indent_size = 2

.github/workflows/github-pages.yaml

@@ -0,0 +1,47 @@
+name: GitHub Pages
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-20.04
+    env:
+      DEPLOY_DIR: docs/_site/
+      DEPLOY_BRANCH: gh-pages
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Prepare branch
+        run: |
+          mkdir "${DEPLOY_DIR}"
+          cd "${DEPLOY_DIR}"
+          # Clone and checkout existing branch, or initialise with a new and empty branch
+          git clone --depth 5 --branch "${DEPLOY_BRANCH}" "https://github.com/${GITHUB_REPOSITORY}.git" . || git init -b "${DEPLOY_BRANCH}"
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.7
+          bundler-cache: true
+          # If your site is in a subdirectory
+          working-directory: ./docs/
+
+      - name: Jekyll build
+        # If your site is in a subdirectory
+        working-directory: ./docs/
+        run: bundle exec jekyll build
+
+      - name: Push to branch
+        # Inspired by https://github.com/helaili/jekyll-action/blob/2.2.0/entrypoint.sh
+        env:
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+        run: |
+          cd "${DEPLOY_DIR}"
+          touch .nojekyll
+          git config user.name "${GITHUB_ACTOR}" && \
+          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com" && \
+          git add . && \
+          git commit --allow-empty -m "Build commit ${GITHUB_SHA}" && \
+          git push "https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "HEAD:${DEPLOY_BRANCH}"

.gitignore

@@ -2,6 +2,7 @@
 /__codeorigin/
 /coverage/
 /docs/_site/
+/docs/.jekyll-cache/
 /docs/Gemfile.lock
 /test/integration/*/package-lock.json
 /test/integration/*/node_modules/

docs/Gemfile

@@ -1,10 +1,8 @@
 source "https://rubygems.org"
 ruby RUBY_VERSION
 
-# To upgrade, run `bundle update github-pages`.
-gem "github-pages", group: :jekyll_plugins
+# To apply changes, run `bundle update`.
+gem "jekyll-theme-amethyst", "0.4.1", group: :jekyll_plugins
 
-# Temporary fix for https://github.com/github/pages-gem/issues/752
-gem "webrick", "~> 1.7"
-
-gem 'jekyll-algolia', "1.7.0", group: :jekyll_plugins
+# Search
+gem "jekyll-algolia", "~> 1.7.0", group: :jekyll_plugins

docs/QUnit/module.md

@@ -10,10 +10,10 @@ redirect_from:
 version_added: "1.0.0"
 ---
 
-`QUnit.module( name [, options] [, nested ] )`<br>
-`QUnit.module.only( name [, options] [, nested ] )`<br>
-`QUnit.module.skip( name [, options] [, nested ] )`<br>
-`QUnit.module.todo( name [, options] [, nested ] )`
+`QUnit.module( name )`<br>
+`QUnit.module( name, nested )`<br>
+`QUnit.module( name, options )`<br>
+`QUnit.module( name, options, nested )`
 
 Group related tests under a common label.
 
@@ -23,22 +23,13 @@ Group related tests under a common label.
 | [`options`](#options-object) (object) | Set hook callbacks to run before or after test execution. |
 | [`nested`](#nested-scope) (function) | A scope to create nested modules and/or set hooks functionally. |
 
-## Description
-
-You can modules organize, select, and filter tests to run. See [§ Example: Organizing tests](#example-organizing-tests).
-
 All tests inside a module will be grouped under that module. The test names will be preceded by the module name in the test results. Tests can be added to a module using the [QUnit.test](./test.md) method.
 
-Modules can be nested inside other modules, in which case their tests' names will be labeled by their names recursively prefixed by their parent modules. See [§ Nested scope](#nested-scope).
-
-The `QUnit.module.only()`, `QUnit.module.skip()`, and `QUnit.module.todo()` methods are aliases for `QUnit.module()` that apply the behaviour of [`QUnit.test.only()`](./test.only.md), [`QUnit.test.skip()`](./test.skip.md) or [`QUnit.test.todo()`](./test.todo.md) to all a module's tests at once.
+You can use modules to organize, select, and filter tests to run. See [§ Organizing your tests](#organizing-your-tests).
 
-### Changelog
+Modules can be nested inside other modules. In the output, tests are generally prefixed by the names of all parent modules. E.g. "Grantparent > Parent > Child > my test". See [§ Nested module scope](#nested-module-scope).
 
-| [QUnit 2.4](https://github.com/qunitjs/qunit/releases/tag/2.4.0) | The `QUnit.module.only()`, `QUnit.module.skip()`, and `QUnit.module.todo()` aliases were introduced.
-| [QUnit 2.0](https://github.com/qunitjs/qunit/releases/tag/2.0.0) | The `before` and `after` options were introduced.
-| [QUnit 1.20](https://github.com/qunitjs/qunit/releases/tag/1.20.0) | The `nested` scope feature was introduced.
-| [QUnit 1.16](https://github.com/qunitjs/qunit/releases/tag/1.16.0) | The `beforeEach` and `afterEach` options were introduced.<br/>The `setup` and `teardown` options were deprecated in QUnit 1.16 and removed in QUnit 2.0.
+The `QUnit.module.only()`, `QUnit.module.skip()`, and `QUnit.module.todo()` methods are aliases for `QUnit.module()` that apply the behaviour of [`QUnit.test.only()`](./test.only.md), [`QUnit.test.skip()`](./test.skip.md) or [`QUnit.test.todo()`](./test.todo.md) to all a module's tests at once.
 
 ### Options object
 
@@ -56,7 +47,7 @@ teardown logic. These hooks can run around individual tests, or around a whole m
 
 **Note**: If additional tests are defined after the module's queue has emptied, it will not run the `after` hook again.
 
-Each [QUnit.test](./test.md) has its own test context object, accessible via its `this` variable. Properties on the module options object are copied over to the test context object at the start of each test. Such properties can also be changed from the hook callbacks. See [§ Example: Test context](#example-test-context).
+Each [QUnit.test](./test.md) has its own test context object, accessible via its `this` variable. Properties on the module options object are copied over to the test context object at the start of each test. Such properties can also be changed from the hook callbacks. See [§ Using the test context](#using-the-test-context).
 
 ### Nested scope
 
@@ -74,11 +65,16 @@ QUnit will run tests on the parent module before those of nested ones, even if l
 [queue]: https://en.wikipedia.org/wiki/Queue_%28abstract_data_type%29
 [stack]: https://en.wikipedia.org/wiki/Stack_%28abstract_data_type%29
 
----
+## Changelog
+
+| [QUnit 2.4](https://github.com/qunitjs/qunit/releases/tag/2.4.0) | The `QUnit.module.only()`, `QUnit.module.skip()`, and `QUnit.module.todo()` aliases were introduced.
+| [QUnit 2.0](https://github.com/qunitjs/qunit/releases/tag/2.0.0) | The `before` and `after` options were introduced.
+| [QUnit 1.20](https://github.com/qunitjs/qunit/releases/tag/1.20.0) | The `nested` scope feature was introduced.
+| [QUnit 1.16](https://github.com/qunitjs/qunit/releases/tag/1.16.0) | The `beforeEach` and `afterEach` options were introduced.<br/>The `setup` and `teardown` options were deprecated in QUnit 1.16 and removed in QUnit 2.0.
 
 ## Examples
 
-### Example: Organizing tests
+### Organizing your tests
 
 If `QUnit.module` is defined without a `nested` callback argument, all subsequently defined tests will be grouped into the module until another module is defined.
 
@@ -126,7 +122,7 @@ test( "basic test example 4", assert => {
 });
 ```
 
-### Example: Declaring hook options
+### Declaring hook options
 
 ```js
 QUnit.module( "module A", {
@@ -145,7 +141,7 @@ QUnit.module( "module A", {
 });
 ```
 
-### Example: Nested scope
+### Nested module scope
 
 ```js
 const { test } = QUnit;
@@ -173,7 +169,7 @@ QUnit.module( "Group B", hooks => {
 });
 ```
 
-### Example: Hooks on nested modules
+### Hooks on nested modules
 
 Use `before`/`beforeEach` hooks are queued for nested modules. `after`/`afterEach` hooks are stacked on nested modules.
 
@@ -218,7 +214,7 @@ QUnit.module( "My Group", hooks => {
 });
 ```
 
-### Example: Test context
+### Using the test context
 
 The test context object is exposed to hook callbacks.
 
@@ -296,7 +292,7 @@ QUnit.module( "Machine Maker", hooks => {
 });
 ```
 
----
+### Module hook with Promise
 
 An example of handling an asynchronous `then`able Promise result in hooks. This example uses an [ES6 Promise][] interface that is fulfilled after connecting to or disconnecting from database.
 
@@ -329,7 +325,7 @@ QUnit.module( "Database connection", {
 });
 ```
 
-### Example: Only run a subset of tests
+### Only run a subset of tests
 
 Use `QUnit.module.only()` to treat an entire module's tests as if they used [`QUnit.test.only`](./test.only.md) instead of [`QUnit.test`](./test.md).
 

docs/QUnit/test.each.md

@@ -20,15 +20,13 @@ Add tests using a data provider.
 | `dataset` (array) | Array or object of data values passed to each test case |
 | `callback` (function) | Function to close over assertions |
 
-### Callback parameters: `callback( assert, data )`:
+### Callback parameters
 
 | parameter | description |
 |-----------|-------------|
 | `assert` (object) | A new instance object with the [assertion methods](../assert/index.md) |
 | `data` (any) | Data value |
 
-## Description
-
 Use this method to add multiple tests that are similar, but with different data passed in.
 
 `QUnit.test.each()` generates multiple calls to [`QUnit.test()`](./test.md) internally, and has all the same capabilities such support for async functions, returning a Promise, and the `assert` argument.
@@ -39,7 +37,7 @@ The [`only`](./test.only.md), [`skip`](./test.skip.md), and [`todo`](./test.todo
 
 ## Examples
 
-### Example: Basic data provider
+### Basic data provider
 
 ```js
 function isEven( x ) {
@@ -51,7 +49,7 @@ QUnit.test.each( "isEven()", [ 2, 4, 6 ], ( assert, data ) => {
 });
 ```
 
-### Example: Array data provider
+### Array data provider
 
 The original array is passed to your callback. [Array destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) can be used to unpack the data array, directly from the callback signature.
 
@@ -69,7 +67,7 @@ QUnit.test.each( "square()", [
 });
 ```
 
-### Example: Object data provider
+### Object data provider
 
 ```js
 QUnit.test.each( "isEven()", {
@@ -80,7 +78,7 @@ QUnit.test.each( "isEven()", {
 });
 ```
 
-### Example: Async functions with `each()`
+### Async functions with `each()`
 
 ```js
 function isEven( x ) {

docs/QUnit/test.md

@@ -1,7 +1,7 @@
 ---
 layout: page-api
 title: QUnit.test()
-excerpt: Add a test to run.
+excerpt: Define a test.
 groups:
   - main
   - async
@@ -15,24 +15,20 @@ version_added: "1.0.0"
 
 `QUnit.test( name, callback )`
 
-Add a test to run.
+Define a test using `QUnit.test()`.
 
 | parameter | description |
 |-----------|-------------|
 | `name` (string) | Title of unit being tested |
 | `callback` (function) | Function to close over assertions |
 
-### Callback parameters: `callback( assert )`:
+### Callback parameters
 
 | parameter | description |
 |-----------|-------------|
-| `assert` (object) | A new instance object with the [assertion methods](../assert/index.md) |
+| `assert` (object) | An [Assert](../assert/index.md) object |
 
-## Description
-
-Add a test to run using `QUnit.test()`.
-
-The `assert` argument to the callback contains all of QUnit's [assertion methods](../assert/index.md). Use this argument to call your test assertions.
+The `assert` argument to the callback contains all of QUnit's [assertion methods](../assert/index.md). Use this to make your test assertions.
 
 `QUnit.test()` can automatically handle the asynchronous resolution of a Promise on your behalf if you return a "then-able" Promise as the result of your callback function.
 
@@ -41,14 +37,15 @@ See also:
 * [`QUnit.test.skip()`](./test.skip.md)
 * [`QUnit.test.todo()`](./test.todo.md)
 
-### Changelog
+## Changelog
 
 | [QUnit 1.16](https://github.com/qunitjs/qunit/releases/tag/1.16.0) | Added support for async functions, and returning of a Promise.
 
-
 ## Examples
 
-A practical example, using the assert argument and no globals.
+### Example: Standard test
+
+A practical example, using the assert argument.
 
 ```js
 function square( x ) {
@@ -61,27 +58,7 @@ QUnit.test( "square()", assert => {
 });
 ```
 
----
-
-An example of handling an asynchronous "then-able" Promise result. This example uses an [ES6 Promise][] interface that is fulfilled after waiting 500ms.
-
-[ES6 Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
-
-```js
-function fetchSquare( x ) {
-  return new Promise( resolve => {
-    setTimeout(() => { resolve( x * x ); }, 1000);
-  });
-}
-
-QUnit.test( "Test with Promise", assert => {
-  return fetchSquare( 3 ).then( result => {
-    assert.equal( result, 9 );
-  });
-});
-```
-
----
+### Example: Async test
 
 Following the example above, `QUnit.test` also supports JS [async functions][] syntax out of the box.
 
@@ -97,3 +74,28 @@ QUnit.test( "Test with async-await", async assert => {
   assert.equal( await fetchSquare(5), 25 );
 });
 ```
+
+
+### Example: Test with Promise
+
+In ES5 and older environments, you can also return a [Promise] from your standard test function. This also supports other then-able, values such as `jQuery.Deferred`, and Bluebird Promise.
+
+This example returns a Promise that is resolved after waiting for 1 second.
+
+[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
+
+```js
+function fetchSquare( x ) {
+  return new Promise( function ( resolve ) {
+    setTimeout( function () {
+      resolve( x * x );
+    }, 1000 );
+  });
+}
+
+QUnit.test( "Test with Promise", assert => {
+  return fetchSquare( 3 ).then( result => {
+    assert.equal( result, 9 );
+  });
+});
+```

docs/QUnit/test.only.md

@@ -20,14 +20,12 @@ Add a test that is exclusively run, preventing other tests from running unless t
 | `name` (string) | Title of unit being tested |
 | `callback` (function) | Function to close over assertions |
 
-### Callback parameters: `callback( assert )`:
+### Callback parameters
 
 | parameter | description |
 |-----------|-------------|
 | `assert` (object) | A new instance object with the [assertion methods](../assert/index.md) |
 
-## Description
-
 Use this method to focus your test suite on specific tests. `QUnit.only` will cause any other tests in your suite to be ignored.
 
 This method is an alternative to re-running individual tests from the HTML reporter interface, and can be especially useful as it can be done upfront without first running the test suite, e.g. in a codebase with many long-running tests.
@@ -36,7 +34,7 @@ It can also be used instead of the `--filter` CLI option, e.g. if you're already
 
 When debugging a larger area of code, you may want to _only_ run all tests within a given module. You can also use[`QUnit.module.only()`](./module.md) to automatically mark all tests in a module as "only" tests.
 
-### Changelog
+## Changelog
 
 | [QUnit 2.12](https://github.com/qunitjs/qunit/releases/tag/2.12.0) | The `QUnit.only()` method was renamed to `QUnit.test.only()`.<br/>Use of `QUnit.only()` remains supported as an alias.
 | [QUnit 1.20](https://github.com/qunitjs/qunit/releases/tag/1.20.0) | The `QUnit.only()` method was introduced.