Merge pull request #330 from bmish/eslint-doc-generator

Automate docs with eslint-doc-generator

.eslintrc.json

@@ -298,6 +298,7 @@
             "files": ["lib/rules/**/*.js", "test/rules/**/*.js"],
             "extends": [ "plugin:eslint-plugin/recommended" ],
             "rules": {
+                "eslint-plugin/require-meta-docs-description": ["error", { "pattern": "^(Enforce|Require|Disallow)" }],
                 "eslint-plugin/require-meta-docs-url": [
                     "error",
                     { "pattern": "https://github.com/lo1tuma/eslint-plugin-mocha/blob/master/docs/rules/{{name}}.md" }

.markdownlint.json

@@ -1,4 +1,5 @@
 {
+    "first-line-h1": false,
     "line-length": false,
-    "first-line-h1": false
+    "no-inline-html": { "allowed_elements": ["sup"] }
   }

README.md

@@ -47,7 +47,9 @@ This plugin supports the following settings, which are used by multiple rules:
 }
 ```
 
-### Recommended config
+## Configs
+
+### `recommended`
 
 This plugin exports a recommended config that enforces good practices.
 
@@ -61,8 +63,46 @@ Enable it with the extends option:
 }
 ```
 
-See [Configuring Eslint](http://eslint.org/docs/user-guide/configuring) on [eslint.org](http://eslint.org) for more info.
+### `all`
 
-## Rules documentation
+There's also a configuration that enables all of our rules.
+
+See [Configuring Eslint](http://eslint.org/docs/user-guide/configuring) on [eslint.org](http://eslint.org) for more info.
 
-The documentation of the rules [can be found here](docs/rules).
+## Rules
+
+<!-- begin auto-generated rules list -->
+
+💼 [Configurations](https://github.com/lo1tuma/eslint-plugin-mocha#configs) enabled in.\
+⚠️ [Configurations](https://github.com/lo1tuma/eslint-plugin-mocha#configs) set to warn in.\
+🚫 [Configurations](https://github.com/lo1tuma/eslint-plugin-mocha#configs) disabled in.\
+✅ Set in the `recommended` [configuration](https://github.com/lo1tuma/eslint-plugin-mocha#configs).\
+🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).
+
+| Name                                                               | Description                                                             | 💼 | ⚠️ | 🚫 | 🔧 |
+| :----------------------------------------------------------------- | :---------------------------------------------------------------------- | :- | :- | :- | :- |
+| [handle-done-callback](docs/rules/handle-done-callback.md)         | Enforces handling of callbacks for async tests                          | ✅  |    |    |    |
+| [max-top-level-suites](docs/rules/max-top-level-suites.md)         | Enforce the number of top-level suites in a single file                 | ✅  |    |    |    |
+| [no-async-describe](docs/rules/no-async-describe.md)               | Disallow async functions passed to describe                             | ✅  |    |    | 🔧 |
+| [no-empty-description](docs/rules/no-empty-description.md)         | Disallow empty test descriptions                                        | ✅  |    |    |    |
+| [no-exclusive-tests](docs/rules/no-exclusive-tests.md)             | Disallow exclusive tests                                                |    | ✅  |    |    |
+| [no-exports](docs/rules/no-exports.md)                             | Disallow exports from test files                                        | ✅  |    |    |    |
+| [no-global-tests](docs/rules/no-global-tests.md)                   | Disallow global tests                                                   | ✅  |    |    |    |
+| [no-hooks](docs/rules/no-hooks.md)                                 | Disallow hooks                                                          |    |    | ✅  |    |
+| [no-hooks-for-single-case](docs/rules/no-hooks-for-single-case.md) | Disallow hooks for a single test or test suite                          |    |    | ✅  |    |
+| [no-identical-title](docs/rules/no-identical-title.md)             | Disallow identical titles                                               | ✅  |    |    |    |
+| [no-mocha-arrows](docs/rules/no-mocha-arrows.md)                   | Disallow arrow functions as arguments to mocha functions                | ✅  |    |    | 🔧 |
+| [no-nested-tests](docs/rules/no-nested-tests.md)                   | Disallow tests to be nested within other tests                          | ✅  |    |    |    |
+| [no-pending-tests](docs/rules/no-pending-tests.md)                 | Disallow pending tests                                                  |    | ✅  |    |    |
+| [no-return-and-callback](docs/rules/no-return-and-callback.md)     | Disallow returning in a test or hook function that uses a callback      | ✅  |    |    |    |
+| [no-return-from-async](docs/rules/no-return-from-async.md)         | Disallow returning from an async test or hook                           |    |    | ✅  |    |
+| [no-setup-in-describe](docs/rules/no-setup-in-describe.md)         | Disallow setup in describe blocks                                       | ✅  |    |    |    |
+| [no-sibling-hooks](docs/rules/no-sibling-hooks.md)                 | Disallow duplicate uses of a hook at the same level inside a describe   | ✅  |    |    |    |
+| [no-skipped-tests](docs/rules/no-skipped-tests.md)                 | Disallow skipped tests                                                  |    | ✅  |    |    |
+| [no-synchronous-tests](docs/rules/no-synchronous-tests.md)         | Disallow synchronous tests                                              |    |    | ✅  |    |
+| [no-top-level-hooks](docs/rules/no-top-level-hooks.md)             | Disallow top-level hooks                                                |    | ✅  |    |    |
+| [prefer-arrow-callback](docs/rules/prefer-arrow-callback.md)       | Require using arrow functions for callbacks                             |    |    | ✅  | 🔧 |
+| [valid-suite-description](docs/rules/valid-suite-description.md)   | Require suite descriptions to match a pre-configured regular expression |    |    | ✅  |    |
+| [valid-test-description](docs/rules/valid-test-description.md)     | Require test descriptions to match a pre-configured regular expression  |    |    | ✅  |    |
+
+<!-- end auto-generated rules list -->

docs/rules/README.md

@@ -1,29 +1 @@
-# Rules
-
-|recommended (level*)|fixable|rule|description|
-|-|-|-|-|
-|:heavy_check_mark: (error)|| [handle-done-callback](handle-done-callback.md) | enforces handling of callbacks for async tests
-|:heavy_check_mark: (error)|| [max-top-level-suites](max-top-level-suites.md) | limit the number of top-level suites in a single file
-|:heavy_check_mark: (error)|:wrench:| [no-async-describe](no-async-describe.md) | disallow async functions passed to describe
-|:heavy_check_mark: (warn)|| [no-exclusive-tests](no-exclusive-tests.md) | disallow exclusive mocha tests
-|:heavy_check_mark: (error)|| [no-exports](no-exports.md) | disallow exports from test files
-|:heavy_check_mark: (error)|| [no-global-tests](no-global-tests.md) | disallow global tests
-||| [no-hooks](no-hooks.md) | disallow hooks
-||| [no-hooks-for-single-case](no-hooks-for-single-case.md) | disallow hooks for a single test or test suite
-|:heavy_check_mark: (error)|| [no-identical-title](no-identical-title.md) | disallow identical titles
-|:heavy_check_mark: (error)|:wrench:| [no-mocha-arrows](no-mocha-arrows.md) | disallow arrow functions as arguments to mocha globals
-|:heavy_check_mark: (error)|| [no-nested-tests](no-nested-tests.md) | disallow tests to be nested within other tests
-|:heavy_check_mark: (warn)|| [no-pending-tests](no-pending-tests.md) | disallow pending/unimplemented mocha tests
-|:heavy_check_mark: (error)|| [no-return-and-callback](no-return-and-callback.md) | disallow returning in a test or hook function that uses a callback
-||| [no-return-from-async](no-return-from-async.md) | disallow returning from an async test or hook
-|:heavy_check_mark: (error)|| [no-setup-in-describe](no-setup-in-describe.md) | disallow calling functions and dot operators directly in describe blocks
-|:heavy_check_mark: (error) || [no-sibling-hooks](no-sibling-hooks.md) | disallow duplicate uses of a hook at the same level inside a describe
-|:heavy_check_mark: (warn)|| [no-skipped-tests](no-skipped-tests.md) | disallow skipped mocha tests
-||| [no-synchronous-tests](no-synchronous-tests.md) | disallow synchronous tests
-|:heavy_check_mark:(warn)|| [no-top-level-hooks](no-top-level-hooks.md) | disallow top-level hooks
-||:wrench:| [prefer-arrow-callback](prefer-arrow-callback.md) | prefer arrow function callbacks (mocha-aware)
-||| [valid-suite-description](valid-suite-description.md) | match suite descriptions against a pre-configured regular expression
-||| [valid-test-description](valid-test-description.md) | match test descriptions against a pre-configured regular expression
-|:heavy_check_mark: (error)|| [no-empty-description](no-empty-description.md) | Disallow empty test descriptions
-
-*: level is defined in [index](../../index.js) file, `configs.recommended.rules` key
+See the rules section of the top-level [README](../../README.md#rules).

docs/rules/handle-done-callback.md

@@ -1,4 +1,8 @@
-# Enforces handling of callbacks for async tests (handle-done-callback)
+# Enforces handling of callbacks for async tests (`mocha/handle-done-callback`)
+
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Mocha allows you to write asynchronous tests by adding a `done` callback to the parameters of your test function.
 It is easy to forget calling this callback after the asynchronous operation is done.

docs/rules/max-top-level-suites.md

@@ -1,4 +1,8 @@
-# Limit the number of top-level suites in a single file (max-top-level-suites)
+# Enforce the number of top-level suites in a single file (`mocha/max-top-level-suites`)
+
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 This rule enforces having a limited amount of top-level suites in a file - by default a single suite per file is allowed.
 

docs/rules/no-async-describe.md

@@ -1,4 +1,10 @@
-# Disallow async functions passed to describe (no-async-describe)
+# Disallow async functions passed to describe (`mocha/no-async-describe`)
+
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
 
 This rule disallows the use of an async function with `describe`. It usually indicates a copy/paste error or that you're trying to use `describe` for setup code, which should happen in `before` or `beforeEach`. Also, it can lead to [the contained `it` blocks not being picked up](https://github.com/mochajs/mocha/issues/2975).
 
@@ -15,8 +21,6 @@ describe('the thing', async function () {
 });
 ```
 
-**Fixable:** Problems detected by this rule are automatically fixable using the `--fix` flag on the command line.
-
 ## Rule Details
 
 The rule supports "describe", "context" and "suite" suite function names and different valid suite name prefixes like "skip" or "only".

docs/rules/no-empty-description.md

@@ -1,4 +1,8 @@
-# Disallow empty test descriptions (no-empty-description)
+# Disallow empty test descriptions (`mocha/no-empty-description`)
+
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 This rule enforces you to specify the suite/test descriptions for each test.
 

docs/rules/no-exclusive-tests.md

@@ -1,4 +1,8 @@
-# Disallow Exclusive Tests (no-exclusive-tests)
+# Disallow exclusive tests (`mocha/no-exclusive-tests`)
+
+⚠️ This rule _warns_ in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Mocha has a feature that allows you to run tests exclusively by appending `.only` to a test-suite or a test-case.
 This feature is really helpful to debug a failing test, so you don’t have to execute all of your tests.

docs/rules/no-exports.md

@@ -1,4 +1,8 @@
-# Disallow exports from test files (no-exports)
+# Disallow exports from test files (`mocha/no-exports`)
+
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Test files should have only one purpose, which is testing a specific unit. Using exports could mean the test file is also used to provide and expose utility or library functionalities, instead those should be moved to separate files.
 

docs/rules/no-global-tests.md

@@ -1,4 +1,8 @@
-# Disallow global tests (no-global-tests)
+# Disallow global tests (`mocha/no-global-tests`)
+
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Mocha gives you the possibility to structure your tests inside of suites using `describe`, `suite` or `context`.
 

docs/rules/no-hooks-for-single-case.md

@@ -1,4 +1,8 @@
-# Disallow hooks for a single test or test suite (no-hooks-for-single-case)
+# Disallow hooks for a single test or test suite (`mocha/no-hooks-for-single-case`)
+
+🚫 This rule is _disabled_ in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Mocha proposes hooks that allow code to be run before or after every or all tests. This helps define a common setup or teardown process for every test. These hooks are not useful when there is only one test case, as it would then make more sense to move the hooks' operations in the test directly.
 

docs/rules/no-hooks.md

@@ -1,4 +1,8 @@
-# Disallow hooks (no-hooks)
+# Disallow hooks (`mocha/no-hooks`)
+
+🚫 This rule is _disabled_ in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Mocha proposes hooks that allow code to be run before or after every or all tests. This helps define a common setup or teardown process for every test. The use of these hooks promotes the use of shared state between the tests, and defeats the purpose of having isolated unit tests.
 

docs/rules/no-identical-title.md

@@ -1,4 +1,8 @@
-# Disallow identical titles (no-identical-title)
+# Disallow identical titles (`mocha/no-identical-title`)
+
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Having identical titles for two different tests or test suites may create confusion. For example, when a test with the same title as another test in the same test suite fails, it is harder to know which one failed and thus harder to fix.
 

docs/rules/no-mocha-arrows.md

@@ -1,8 +1,12 @@
-# Disallow Arrow Functions as Arguments to Mocha Functions (no-mocha-arrows)
+# Disallow arrow functions as arguments to mocha functions (`mocha/no-mocha-arrows`)
 
-Mocha [discourages](http://mochajs.org/#arrow-functions) passing it arrow functions as arguments. This rule prevents their use on the Mocha globals.
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
-**Fixable:** Problems detected by this rule are automatically fixable using the `--fix` flag on the command line.
+<!-- end auto-generated rule header -->
+
+Mocha [discourages](http://mochajs.org/#arrow-functions) passing it arrow functions as arguments. This rule prevents their use on the Mocha globals.
 
 ## Rule Details
 

docs/rules/no-nested-tests.md

@@ -1,4 +1,8 @@
-# Disallow tests to be nested within other tests (no-nested-tests)
+# Disallow tests to be nested within other tests (`mocha/no-nested-tests`)
+
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Test cases in mocha can be either global or within a suite but they can’t be nested within other tests. Unfortunately there is nothing stopping you from creating a test case within another test case but mocha will simply ignore those tests.
 

docs/rules/no-pending-tests.md

@@ -1,4 +1,8 @@
-# Disallow Pending Tests (no-pending-tests)
+# Disallow pending tests (`mocha/no-pending-tests`)
+
+⚠️ This rule _warns_ in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Mocha allows specification of pending tests, which represent tests that aren't yet implemented, but are intended to be implemented eventually. These are designated like a normal mocha test, but with only the first argument provided (no callback for the actual implementation). For example: `it('unimplemented test');`
 

docs/rules/no-return-and-callback.md

@@ -1,4 +1,8 @@
-# Disallow returning in a test or hook function that uses a callback (no-return-and-callback)
+# Disallow returning in a test or hook function that uses a callback (`mocha/no-return-and-callback`)
+
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Mocha's tests or hooks (like `before`) may be asynchronous by either returning a Promise or specifying a callback parameter for the function. It can be confusing to have both methods used in a test or hook, and from Mocha v3 on, causes the test to fail in order to force developers to remove this source of confusion.
 

docs/rules/no-return-from-async.md

@@ -1,4 +1,8 @@
-# Disallow returning from an async test or hook (no-return-from-async)
+# Disallow returning from an async test or hook (`mocha/no-return-from-async`)
+
+🚫 This rule is _disabled_ in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Mocha's tests or hooks (like `before`) may be asynchronous by returning a Promise. When such a Promise-returning function is defined using [an ES7 `async` function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) it can be confusing when combined with an explicit `return` of a Promise, as it's mixing the two styles.
 

docs/rules/no-setup-in-describe.md

@@ -1,4 +1,8 @@
-# Disallow setup in describe blocks (no-setup-in-describe)
+# Disallow setup in describe blocks (`mocha/no-setup-in-describe`)
+
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Setup for test cases in mocha should be done in `before`, `beforeEach`, or `it` blocks. Unfortunately there is nothing stopping you from doing setup directly inside a `describe` block.
 

docs/rules/no-sibling-hooks.md

@@ -1,4 +1,8 @@
-# Disallow duplicate uses of a hook at the same level inside a describe (no-sibling-hooks)
+# Disallow duplicate uses of a hook at the same level inside a describe (`mocha/no-sibling-hooks`)
+
+💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Mocha proposes hooks that allow code to be run before or after every or all tests. This helps define a common setup or teardown process for every test.
 It is possible to declare a hook multiple times inside the same test suite, but it can be confusing. It is better to have one hook handle the whole of the setup or teardown logic of the test suite.

docs/rules/no-skipped-tests.md

@@ -1,4 +1,8 @@
-# Disallow Skipped Tests (no-skipped-tests)
+# Disallow skipped tests (`mocha/no-skipped-tests`)
+
+⚠️ This rule _warns_ in the ✅ `recommended` [config](https://github.com/lo1tuma/eslint-plugin-mocha#configs).
+
+<!-- end auto-generated rule header -->
 
 Mocha has a feature that allows you to skip tests by appending `.skip` to a test-suite or a test-case, or by prepending it with an `x` (e.g., `xdescribe(...)` instead of `describe(...)`).
 Sometimes tests are skipped as part of a debugging process, and aren't intended to be committed.  This rule reminds you to remove `.skip` or the `x` prefix from your tests.