fix: consistent rule doc notices and sections (#1226)

Co-authored-by: Gareth Jones <[email protected]>

Author: bmish

README.md

@@ -215,6 +215,7 @@ installations requiring long-term consistency.
 | [no-focused-tests](docs/rules/no-focused-tests.md)                           | Disallow focused tests                                              | ![recommended][] | ![suggest][] |
 | [no-hooks](docs/rules/no-hooks.md)                                           | Disallow setup and teardown hooks                                   |                  |              |
 | [no-identical-title](docs/rules/no-identical-title.md)                       | Disallow identical titles                                           | ![recommended][] |              |
+| [no-if](docs/rules/no-if.md)                                                 | Disallow conditional logic                                          | ![deprecated][]  |              |
 | [no-interpolation-in-snapshots](docs/rules/no-interpolation-in-snapshots.md) | Disallow string interpolation inside snapshots                      | ![recommended][] |              |
 | [no-jasmine-globals](docs/rules/no-jasmine-globals.md)                       | Disallow Jasmine globals                                            | ![recommended][] | ![fixable][] |
 | [no-large-snapshots](docs/rules/no-large-snapshots.md)                       | disallow large snapshots                                            |                  |              |
@@ -308,4 +309,5 @@ https://github.com/istanbuljs/eslint-plugin-istanbul
 [suggest]: https://img.shields.io/badge/-suggest-yellow.svg
 [fixable]: https://img.shields.io/badge/-fixable-green.svg
 [style]: https://img.shields.io/badge/-style-blue.svg
+[deprecated]: https://img.shields.io/badge/-deprecated-red.svg
 [`no-deprecated-functions`]: docs/rules/no-deprecated-functions.md

docs/rules/consistent-test-it.md

@@ -1,14 +1,26 @@
 # Have control over `test` and `it` usages (`consistent-test-it`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`.
+
+🔧 This rule is automatically fixable using the `--fix`
+[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
+on the command line.
+
+<!-- end rule header -->
+
 Jest allows you to choose how you want to define your tests, using the `it` or
 the `test` keywords, with multiple permutations for each:
 
 - **it:** `it`, `xit`, `fit`, `it.only`, `it.skip`.
 - **test:** `test`, `xtest`, `test.only`, `test.skip`.
 
+## Rule details
+
 This rule gives you control over the usage of these keywords in your codebase.
 
-## Rule Details
+## Options
 
 This rule can be configured as follows
 

docs/rules/expect-expect.md

@@ -1,5 +1,11 @@
 # Enforce assertion to be made in a test body (`expect-expect`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`.
+
+<!-- end rule header -->
+
 Ensure that there is at least one `expect` call made in a test.
 
 ## Rule details

docs/rules/max-expects.md

@@ -1,10 +1,16 @@
 # Enforces a maximum number assertion calls in a test body (`max-expects`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`.
+
+<!-- end rule header -->
+
 As more assertions are made, there is a possible tendency for the test to be
 more likely to mix multiple objectives. To avoid this, this rule reports when
 the maximum number of assertions is exceeded.
 
-## Rule Details
+## Rule details
 
 This rule enforces a maximum number of `expect()` calls.
 

docs/rules/max-nested-describe.md

@@ -1,10 +1,16 @@
 # Enforces a maximum depth to nested describe calls (`max-nested-describe`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`.
+
+<!-- end rule header -->
+
 While it's useful to be able to group your tests together within the same file
 using `describe()`, having too many levels of nesting throughout your tests make
 them difficult to read.
 
-## Rule Details
+## Rule details
 
 This rule enforces a maximum depth to nested `describe()` calls to improve code
 clarity in your tests.

docs/rules/no-alias-methods.md

@@ -1,5 +1,15 @@
 # Disallow alias methods (`no-alias-methods`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`, `recommended`.
+
+🔧 This rule is automatically fixable using the `--fix`
+[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
+on the command line.
+
+<!-- end rule header -->
+
 > These aliases are going to be removed in the next major version of Jest - see
 > https://github.com/facebook/jest/issues/13164 for more
 

docs/rules/no-commented-out-tests.md

@@ -1,9 +1,15 @@
 # Disallow commented out tests (`no-commented-out-tests`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`.
+
+<!-- end rule header -->
+
 This rule raises a warning about commented out tests. It's similar to
 no-disabled-tests rule.
 
-## Rule Details
+## Rule details
 
 The rule uses fuzzy matching to do its best to determine what constitutes a
 commented out test, checking for a presence of `it(`, `describe(`, `it.skip(`,

docs/rules/no-conditional-expect.md

@@ -1,12 +1,18 @@
 # Prevent calling `expect` conditionally (`no-conditional-expect`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`, `recommended`.
+
+<!-- end rule header -->
+
 This rule prevents the use of `expect` in conditional blocks, such as `if`s &
 `catch`s.
 
 This includes using `expect` in callbacks to functions named `catch`, which are
 assumed to be promises.
 
-## Rule Details
+## Rule details
 
 Jest only considers a test to have failed if it throws an error, meaning if
 calls to assertion functions like `expect` occur in conditional code such as a

docs/rules/no-conditional-in-test.md

@@ -1,11 +1,17 @@
 # Disallow conditional logic in tests (`no-conditional-in-test`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`.
+
+<!-- end rule header -->
+
 Conditional logic in tests is usually an indication that a test is attempting to
 cover too much, and not testing the logic it intends to. Each branch of code
 executing within a conditional statement will usually be better served by a test
 devoted to it.
 
-## Rule Details
+## Rule details
 
 This rule reports on any use of a conditional statement such as `if`, `switch`,
 and ternary expressions.

docs/rules/no-deprecated-functions.md

@@ -1,5 +1,15 @@
 # Disallow use of deprecated functions (`no-deprecated-functions`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`, `recommended`.
+
+🔧 This rule is automatically fixable using the `--fix`
+[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
+on the command line.
+
+<!-- end rule header -->
+
 Over the years Jest has accrued some debt in the form of functions that have
 either been renamed for clarity, or replaced with more powerful APIs.
 

docs/rules/no-disabled-tests.md

@@ -1,13 +1,19 @@
 # Disallow disabled tests (`no-disabled-tests`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`.
+
+<!-- end rule header -->
+
 Jest has a feature that allows you to temporarily mark tests as disabled. This
 feature is often helpful while debugging or to create placeholders for future
 tests. Before committing changes we may want to check that all tests are
 running.
 
 This rule raises a warning about disabled tests.
 
-## Rule Details
+## Rule details
 
 There are a number of ways to disable tests in Jest:
 

docs/rules/no-done-callback.md

@@ -1,5 +1,15 @@
 # Avoid using a callback in asynchronous tests and hooks (`no-done-callback`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`, `recommended`.
+
+💡 This rule provides
+[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
+that can be applied manually.
+
+<!-- end rule header -->
+
 When calling asynchronous code in hooks and tests, `jest` needs to know when the
 asynchronous work is complete to progress the current run.
 

docs/rules/no-duplicate-hooks.md

@@ -1,8 +1,14 @@
 # Disallow duplicate setup and teardown hooks (`no-duplicate-hooks`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`.
+
+<!-- end rule header -->
+
 A `describe` block should not contain duplicate hooks.
 
-## Rule Details
+## Rule details
 
 Examples of **incorrect** code for this rule
 

docs/rules/no-export.md

@@ -1,8 +1,14 @@
 # Disallow using `exports` in files containing tests (`no-export`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`, `recommended`.
+
+<!-- end rule header -->
+
 Prevents using `exports` if a file has one or more tests in it.
 
-## Rule Details
+## Rule details
 
 This rule aims to eliminate duplicate runs of tests by exporting things from
 test files. If you import from a test file, then all the tests in that file will

docs/rules/no-focused-tests.md

@@ -1,5 +1,16 @@
 # Disallow focused tests (`no-focused-tests`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`, `recommended`.
+
+💡 This rule provides
+[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
+that can be applied manually.
+
+<!-- end rule header -->
+
+<!-- prettier-ignore -->
 Jest has a feature that allows you to focus tests by appending `.only` or
 prepending `f` 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. After you
@@ -9,7 +20,7 @@ have fixed your test and before committing the changes you have to remove
 This rule reminds you to remove `.only` from your tests by raising a warning
 whenever you are using the exclusivity feature.
 
-## Rule Details
+## Rule details
 
 This rule looks for every `describe.only`, `it.only`, `test.only`, `fdescribe`,
 and `fit` occurrences within the source code. Of course there are some

docs/rules/no-hooks.md

@@ -1,10 +1,16 @@
 # Disallow setup and teardown hooks (`no-hooks`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`.
+
+<!-- end rule header -->
+
 Jest provides global functions for setup and teardown tasks, which are called
 before/after each test case and each test suite. The use of these hooks promotes
 shared state between tests.
 
-## Rule Details
+## Rule details
 
 This rule reports for the following function calls:
 

docs/rules/no-identical-title.md

@@ -1,11 +1,17 @@
 # Disallow identical titles (`no-identical-title`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`, `recommended`.
+
+<!-- end 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.
 
-## Rule Details
+## Rule details
 
 This rule looks at the title of every test and test suite. It will report when
 two test suites or two test cases at the same level of a test suite have the

docs/rules/no-if.md

@@ -1,9 +1,9 @@
 # Disallow conditional logic (`no-if`)
 
-## Deprecated
+❌ This rule is deprecated. It was replaced by
+[no-conditional-in-test](no-conditional-in-test.md).
 
-This rule has been deprecated in favor of
-[`no-conditional-in-test`](no-conditional-in-test.md).
+<!-- end rule header -->
 
 Conditional logic in tests is usually an indication that a test is attempting to
 cover too much, and not testing the logic it intends to. Each branch of code
@@ -13,7 +13,7 @@ to it.
 Conditionals are often used to satisfy the typescript type checker. In these
 cases, using the non-null assertion operator (!) would be best.
 
-## Rule Details
+## Rule details
 
 This rule prevents the use of if/ else statements and conditional (ternary)
 operations in tests.

docs/rules/no-interpolation-in-snapshots.md

@@ -1,8 +1,14 @@
 # Disallow string interpolation inside snapshots (`no-interpolation-in-snapshots`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`, `recommended`.
+
+<!-- end rule header -->
+
 Prevents the use of string interpolations in snapshots.
 
-## Rule Details
+## Rule details
 
 Interpolation prevents snapshots from being updated. Instead, properties should
 be overloaded with a matcher by using

docs/rules/no-jasmine-globals.md

@@ -1,13 +1,23 @@
 # Disallow Jasmine globals (`no-jasmine-globals`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`, `recommended`.
+
+🔧 This rule is automatically fixable using the `--fix`
+[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
+on the command line.
+
+<!-- end rule header -->
+
 `jest` uses `jasmine` as a test runner. A side effect of this is that both a
 `jasmine` object, and some jasmine-specific globals, are exposed to the test
 environment. Most functionality offered by Jasmine has been ported to Jest, and
 the Jasmine globals will stop working in the future. Developers should therefore
 migrate to Jest's documented API instead of relying on the undocumented Jasmine
 API.
 
-### Rule details
+## Rule details
 
 This rule reports on any usage of Jasmine globals, which is not ported to Jest,
 and suggests alternatives from Jest's own API.

docs/rules/no-large-snapshots.md

@@ -1,5 +1,11 @@
 # disallow large snapshots (`no-large-snapshots`)
 
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
+`all`.
+
+<!-- end rule header -->
+
 When using Jest's snapshot capability one should be mindful of the size of
 created snapshots. As a general best practice snapshots should be limited in
 size in order to be more manageable and reviewable. A stored snapshot is only as
@@ -22,7 +28,7 @@ module.exports = {
 };
 ```
 
-## Rule Details
+## Rule details
 
 This rule looks at all Jest inline and external snapshots (files with `.snap`
 extension) and validates that each stored snapshot within those files does not