From a16aa6ab67a05faa53fded715ccb89adc8259664 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Sun, 28 Aug 2022 17:29:53 -0400
Subject: [PATCH 01/23] docs: consistent rule doc notices and sections

---
 docs/rules/consistent-test-it.md            |  10 +-
 docs/rules/expect-expect.md                 |   5 +-
 docs/rules/max-expects.md                   |   3 +
 docs/rules/max-nested-describe.md           |   3 +
 docs/rules/no-alias-methods.md              |   8 +-
 docs/rules/no-commented-out-tests.md        |   3 +
 docs/rules/no-conditional-expect.md         |   3 +
 docs/rules/no-conditional-in-test.md        |   3 +
 docs/rules/no-deprecated-functions.md       |   8 +-
 docs/rules/no-disabled-tests.md             |   3 +
 docs/rules/no-done-callback.md              |   8 +-
 docs/rules/no-duplicate-hooks.md            |   3 +
 docs/rules/no-export.md                     |   3 +
 docs/rules/no-focused-tests.md              |   6 +
 docs/rules/no-hooks.md                      |   3 +
 docs/rules/no-identical-title.md            |   3 +
 docs/rules/no-if.md                         |   2 +-
 docs/rules/no-interpolation-in-snapshots.md |   3 +
 docs/rules/no-jasmine-globals.md            |   8 +-
 docs/rules/no-large-snapshots.md            |   3 +
 docs/rules/no-mocks-import.md               |   5 +-
 docs/rules/no-restricted-matchers.md        |   9 +-
 docs/rules/no-standalone-expect.md          |   3 +
 docs/rules/no-test-prefixes.md              |   8 +-
 docs/rules/no-test-return-statement.md      |   5 +-
 docs/rules/prefer-called-with.md            |   5 +-
 docs/rules/prefer-comparison-matcher.md     |   8 +-
 docs/rules/prefer-each.md                   |   5 +-
 docs/rules/prefer-equality-matcher.md       |   8 +-
 docs/rules/prefer-expect-assertions.md      |   8 +-
 docs/rules/prefer-expect-resolves.md        |   8 +-
 docs/rules/prefer-hooks-in-order.md         |   3 +
 docs/rules/prefer-hooks-on-top.md           |   3 +
 docs/rules/prefer-lowercase-title.md        |   8 +-
 docs/rules/prefer-mock-promise-shorthand.md |   6 +
 docs/rules/prefer-snapshot-hint.md          |   5 +-
 docs/rules/prefer-spy-on.md                 |   8 +-
 docs/rules/prefer-strict-equal.md           |   8 +-
 docs/rules/prefer-to-be.md                  |   8 +-
 docs/rules/prefer-to-contain.md             |   8 +-
 docs/rules/prefer-to-have-length.md         |   8 +-
 docs/rules/prefer-todo.md                   |   8 +-
 docs/rules/require-hook.md                  |   5 +-
 docs/rules/require-to-throw-message.md      |   5 +-
 docs/rules/require-top-level-describe.md    |   5 +
 docs/rules/unbound-method.md                |   3 +
 docs/rules/valid-describe-callback.md       |   3 +
 docs/rules/valid-expect-in-promise.md       |   5 +-
 docs/rules/valid-expect.md                  |   5 +-
 docs/rules/valid-title.md                   |   6 +
 src/__tests__/rules.test.ts                 | 137 +++++++++++++++++++-
 51 files changed, 379 insertions(+), 31 deletions(-)

diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md
index 94e74e61b..881073c9c 100644
--- a/docs/rules/consistent-test-it.md
+++ b/docs/rules/consistent-test-it.md
@@ -1,14 +1,22 @@
 # Have control over `test` and `it` usages (`consistent-test-it`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 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
 
diff --git a/docs/rules/expect-expect.md b/docs/rules/expect-expect.md
index 636216067..c9747ea61 100644
--- a/docs/rules/expect-expect.md
+++ b/docs/rules/expect-expect.md
@@ -1,8 +1,11 @@
 # Enforce assertion to be made in a test body (`expect-expect`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 Ensure that there is at least one `expect` call made in a test.
 
-## Rule details
+## Rule Details
 
 This rule triggers when there is no call made to `expect` in a test, to prevent
 users from forgetting to add assertions.
diff --git a/docs/rules/max-expects.md b/docs/rules/max-expects.md
index 1efa59ae7..d5fa1f752 100644
--- a/docs/rules/max-expects.md
+++ b/docs/rules/max-expects.md
@@ -1,5 +1,8 @@
 # Enforces a maximum number assertion calls in a test body (`max-expects`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 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.
diff --git a/docs/rules/max-nested-describe.md b/docs/rules/max-nested-describe.md
index 9f10f9828..0fc83553c 100644
--- a/docs/rules/max-nested-describe.md
+++ b/docs/rules/max-nested-describe.md
@@ -1,5 +1,8 @@
 # Enforces a maximum depth to nested describe calls (`max-nested-describe`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 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.
diff --git a/docs/rules/no-alias-methods.md b/docs/rules/no-alias-methods.md
index d439104de..341151124 100644
--- a/docs/rules/no-alias-methods.md
+++ b/docs/rules/no-alias-methods.md
@@ -1,5 +1,11 @@
 # Disallow alias methods (`no-alias-methods`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 > These aliases are going to be removed in the next major version of Jest - see
 > https://github.com/facebook/jest/issues/13164 for more
 
@@ -9,7 +15,7 @@ Jest documentation is used in the code. This makes it easier to search for all
 occurrences of the method within code, and it ensures consistency among the
 method names used.
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if the alias name, rather than the canonical name,
 of a method is used.
diff --git a/docs/rules/no-commented-out-tests.md b/docs/rules/no-commented-out-tests.md
index b12755c47..adce60fed 100644
--- a/docs/rules/no-commented-out-tests.md
+++ b/docs/rules/no-commented-out-tests.md
@@ -1,5 +1,8 @@
 # Disallow commented out tests (`no-commented-out-tests`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 This rule raises a warning about commented out tests. It's similar to
 no-disabled-tests rule.
 
diff --git a/docs/rules/no-conditional-expect.md b/docs/rules/no-conditional-expect.md
index fc46d3ff7..14d5ae6c3 100644
--- a/docs/rules/no-conditional-expect.md
+++ b/docs/rules/no-conditional-expect.md
@@ -1,5 +1,8 @@
 # Prevent calling `expect` conditionally (`no-conditional-expect`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
 This rule prevents the use of `expect` in conditional blocks, such as `if`s &
 `catch`s.
 
diff --git a/docs/rules/no-conditional-in-test.md b/docs/rules/no-conditional-in-test.md
index 6850cc47f..073724019 100644
--- a/docs/rules/no-conditional-in-test.md
+++ b/docs/rules/no-conditional-in-test.md
@@ -1,5 +1,8 @@
 # Disallow conditional logic in tests (`no-conditional-in-test`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 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
diff --git a/docs/rules/no-deprecated-functions.md b/docs/rules/no-deprecated-functions.md
index e5c0bca67..8f21028fe 100644
--- a/docs/rules/no-deprecated-functions.md
+++ b/docs/rules/no-deprecated-functions.md
@@ -1,5 +1,11 @@
 # Disallow use of deprecated functions (`no-deprecated-functions`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 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.
 
@@ -11,7 +17,7 @@ This rule requires knowing which version of Jest you're using - see
 on how that is obtained automatically and how you can explicitly provide a
 version if needed.
 
-## Rule details
+## Rule Details
 
 This rule warns about calls to deprecated functions, and provides details on
 what to replace them with, based on the version of Jest that is installed.
diff --git a/docs/rules/no-disabled-tests.md b/docs/rules/no-disabled-tests.md
index c6726686a..1e08ff1ac 100644
--- a/docs/rules/no-disabled-tests.md
+++ b/docs/rules/no-disabled-tests.md
@@ -1,5 +1,8 @@
 # Disallow disabled tests (`no-disabled-tests`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 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
diff --git a/docs/rules/no-done-callback.md b/docs/rules/no-done-callback.md
index abae2b017..9c4bfe4c5 100644
--- a/docs/rules/no-done-callback.md
+++ b/docs/rules/no-done-callback.md
@@ -1,5 +1,11 @@
 # Avoid using a callback in asynchronous tests and hooks (`no-done-callback`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
+<!-- prettier-ignore -->
+💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+
 When calling asynchronous code in hooks and tests, `jest` needs to know when the
 asynchronous work is complete to progress the current run.
 
@@ -49,7 +55,7 @@ test('the data is peanut butter', async () => {
 });
 ```
 
-## Rule details
+## Rule Details
 
 This rule checks the function parameter of hooks & tests for use of the `done`
 argument, suggesting you return a promise instead.
diff --git a/docs/rules/no-duplicate-hooks.md b/docs/rules/no-duplicate-hooks.md
index 58b69d5dd..78397e354 100644
--- a/docs/rules/no-duplicate-hooks.md
+++ b/docs/rules/no-duplicate-hooks.md
@@ -1,5 +1,8 @@
 # Disallow duplicate setup and teardown hooks (`no-duplicate-hooks`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 A `describe` block should not contain duplicate hooks.
 
 ## Rule Details
diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md
index f8379b72e..b3b29d2d4 100644
--- a/docs/rules/no-export.md
+++ b/docs/rules/no-export.md
@@ -1,5 +1,8 @@
 # Disallow using `exports` in files containing tests (`no-export`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
 Prevents using `exports` if a file has one or more tests in it.
 
 ## Rule Details
diff --git a/docs/rules/no-focused-tests.md b/docs/rules/no-focused-tests.md
index 22f00bd99..456c09596 100644
--- a/docs/rules/no-focused-tests.md
+++ b/docs/rules/no-focused-tests.md
@@ -1,5 +1,11 @@
 # Disallow focused tests (`no-focused-tests`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
+<!-- prettier-ignore -->
+💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+
 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
diff --git a/docs/rules/no-hooks.md b/docs/rules/no-hooks.md
index 708d3550d..11f040158 100644
--- a/docs/rules/no-hooks.md
+++ b/docs/rules/no-hooks.md
@@ -1,5 +1,8 @@
 # Disallow setup and teardown hooks (`no-hooks`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 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.
diff --git a/docs/rules/no-identical-title.md b/docs/rules/no-identical-title.md
index d56e41e90..ee9b88e41 100644
--- a/docs/rules/no-identical-title.md
+++ b/docs/rules/no-identical-title.md
@@ -1,5 +1,8 @@
 # Disallow identical titles (`no-identical-title`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
 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
diff --git a/docs/rules/no-if.md b/docs/rules/no-if.md
index e44015e0b..b03a066e0 100644
--- a/docs/rules/no-if.md
+++ b/docs/rules/no-if.md
@@ -1,6 +1,6 @@
 # Disallow conditional logic (`no-if`)
 
-## Deprecated
+❌ This rule is deprecated.
 
 This rule has been deprecated in favor of
 [`no-conditional-in-test`](no-conditional-in-test.md).
diff --git a/docs/rules/no-interpolation-in-snapshots.md b/docs/rules/no-interpolation-in-snapshots.md
index 0ac13540e..128e07258 100644
--- a/docs/rules/no-interpolation-in-snapshots.md
+++ b/docs/rules/no-interpolation-in-snapshots.md
@@ -1,5 +1,8 @@
 # Disallow string interpolation inside snapshots (`no-interpolation-in-snapshots`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
 Prevents the use of string interpolations in snapshots.
 
 ## Rule Details
diff --git a/docs/rules/no-jasmine-globals.md b/docs/rules/no-jasmine-globals.md
index 8fbb47356..299e11e3c 100644
--- a/docs/rules/no-jasmine-globals.md
+++ b/docs/rules/no-jasmine-globals.md
@@ -1,5 +1,11 @@
 # Disallow Jasmine globals (`no-jasmine-globals`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 `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
@@ -7,7 +13,7 @@ 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.
diff --git a/docs/rules/no-large-snapshots.md b/docs/rules/no-large-snapshots.md
index 8572fda98..0c2416ef8 100644
--- a/docs/rules/no-large-snapshots.md
+++ b/docs/rules/no-large-snapshots.md
@@ -1,5 +1,8 @@
 # disallow large snapshots (`no-large-snapshots`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 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
diff --git a/docs/rules/no-mocks-import.md b/docs/rules/no-mocks-import.md
index 429ed3241..483ee7851 100644
--- a/docs/rules/no-mocks-import.md
+++ b/docs/rules/no-mocks-import.md
@@ -1,5 +1,8 @@
 # Disallow manually importing from `__mocks__` (`no-mocks-import`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
 When using `jest.mock`, your tests (just like the code being tested) should
 import from `./x`, not `./__mocks__/x`. Not following this rule can lead to
 confusion, because you will have multiple instances of the mocked module:
@@ -14,7 +17,7 @@ test('x', () => {
 });
 ```
 
-### Rule details
+## Rule Details
 
 This rule reports imports from a path containing a `__mocks__` component.
 
diff --git a/docs/rules/no-restricted-matchers.md b/docs/rules/no-restricted-matchers.md
index 77138b558..844d308fe 100644
--- a/docs/rules/no-restricted-matchers.md
+++ b/docs/rules/no-restricted-matchers.md
@@ -1,9 +1,16 @@
 # Disallow specific matchers & modifiers (`no-restricted-matchers`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
+You may want to ban specific matchers & modifiers from being used.
+
+## Rule Details
+
 This rule bans specific matchers & modifiers from being used, and can suggest
 alternatives.
 
-## Rule Details
+## Options
 
 Bans are expressed in the form of a map, with the value being either a string
 message to be shown, or `null` if the default rule message should be used.
diff --git a/docs/rules/no-standalone-expect.md b/docs/rules/no-standalone-expect.md
index efdd4f9cf..36cbf5221 100644
--- a/docs/rules/no-standalone-expect.md
+++ b/docs/rules/no-standalone-expect.md
@@ -1,5 +1,8 @@
 # Disallow using `expect` outside of `it` or `test` blocks (`no-standalone-expect`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
 Prevents `expect` statements outside of a `test` or `it` block. An `expect`
 within a helper function (but outside of a `test` or `it` block) will not
 trigger this rule.
diff --git a/docs/rules/no-test-prefixes.md b/docs/rules/no-test-prefixes.md
index 21b0ba059..65405f8b7 100644
--- a/docs/rules/no-test-prefixes.md
+++ b/docs/rules/no-test-prefixes.md
@@ -1,5 +1,11 @@
 # Use `.only` and `.skip` over `f` and `x` (`no-test-prefixes`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 Jest allows you to choose how you want to define focused and skipped tests, with
 multiple permutations for each:
 
@@ -9,7 +15,7 @@ multiple permutations for each:
 
 This rule enforces usages from the **only & skip** list.
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if you use one of the keywords from the **'f' &
 'x'** list to focus/skip a test.
diff --git a/docs/rules/no-test-return-statement.md b/docs/rules/no-test-return-statement.md
index 6577062cc..e3f7a3694 100644
--- a/docs/rules/no-test-return-statement.md
+++ b/docs/rules/no-test-return-statement.md
@@ -1,11 +1,14 @@
 # Disallow explicitly returning from tests (`no-test-return-statement`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 Tests in Jest should be void and not return values.
 
 If you are returning Promises then you should update the test to use
 `async/await`.
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if you use a return statement inside a test body.
 
diff --git a/docs/rules/prefer-called-with.md b/docs/rules/prefer-called-with.md
index 09bf7360c..f38eda7e7 100644
--- a/docs/rules/prefer-called-with.md
+++ b/docs/rules/prefer-called-with.md
@@ -1,5 +1,8 @@
 # Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` (`prefer-called-with`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 The `toBeCalled()` matcher is used to assert that a mock function has been
 called one or more times, without checking the arguments passed. The assertion
 is stronger when arguments are also validated using the `toBeCalledWith()`
@@ -9,7 +12,7 @@ matcher. When some arguments are difficult to check, using generic match like
 This rule warns if the form without argument checking is used, except for `.not`
 enforcing a function has never been called.
 
-## Rule details
+## Rule Details
 
 The following patterns are warnings:
 
diff --git a/docs/rules/prefer-comparison-matcher.md b/docs/rules/prefer-comparison-matcher.md
index 33c740535..3757d8340 100644
--- a/docs/rules/prefer-comparison-matcher.md
+++ b/docs/rules/prefer-comparison-matcher.md
@@ -1,9 +1,15 @@
 # Suggest using the built-in comparison matchers (`prefer-comparison-matcher`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 Jest has a number of built-in matchers for comparing numbers, which allow for
 more readable tests and error messages if an expectation fails.
 
-## Rule details
+## Rule Details
 
 This rule checks for comparisons in tests that could be replaced with one of the
 following built-in comparison matchers:
diff --git a/docs/rules/prefer-each.md b/docs/rules/prefer-each.md
index cb995ba00..4d42b9060 100644
--- a/docs/rules/prefer-each.md
+++ b/docs/rules/prefer-each.md
@@ -1,8 +1,11 @@
 # Prefer using `.each` rather than manual loops (`prefer-each`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 Reports where you might be able to use `.each` instead of native loops.
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if you use test case functions like `describe`,
 `test`, and `it`, in a native loop - generally you should be able to use `.each`
diff --git a/docs/rules/prefer-equality-matcher.md b/docs/rules/prefer-equality-matcher.md
index d27eb433a..938ad3f8e 100644
--- a/docs/rules/prefer-equality-matcher.md
+++ b/docs/rules/prefer-equality-matcher.md
@@ -1,9 +1,15 @@
 # Suggest using the built-in equality matchers (`prefer-equality-matcher`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
+<!-- prettier-ignore -->
+💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+
 Jest has built-in matchers for expecting equality, which allow for more readable
 tests and error messages if an expectation fails.
 
-## Rule details
+## Rule Details
 
 This rule checks for _strict_ equality checks (`===` & `!==`) in tests that
 could be replaced with one of the following built-in equality matchers:
diff --git a/docs/rules/prefer-expect-assertions.md b/docs/rules/prefer-expect-assertions.md
index 512797217..2638368c1 100644
--- a/docs/rules/prefer-expect-assertions.md
+++ b/docs/rules/prefer-expect-assertions.md
@@ -1,9 +1,15 @@
 # Suggest using `expect.assertions()` OR `expect.hasAssertions()` (`prefer-expect-assertions`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
+<!-- prettier-ignore -->
+💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+
 Ensure every test to have either `expect.assertions(<number of assertions>)` OR
 `expect.hasAssertions()` as its first expression.
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if,
 
diff --git a/docs/rules/prefer-expect-resolves.md b/docs/rules/prefer-expect-resolves.md
index baba945b7..f5f633f30 100644
--- a/docs/rules/prefer-expect-resolves.md
+++ b/docs/rules/prefer-expect-resolves.md
@@ -1,5 +1,11 @@
 # Prefer `await expect(...).resolves` over `expect(await ...)` syntax (`prefer-expect-resolves`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 When working with promises, there are two primary ways you can test the resolved
 value:
 
@@ -15,7 +21,7 @@ behaviour and output from `jest`.
 Additionally, favoring the first style ensures consistency with its `rejects`
 counterpart, as there is no way of "awaiting" a rejection.
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if an `await` is done within an `expect`, and
 recommends using `resolves` instead.
diff --git a/docs/rules/prefer-hooks-in-order.md b/docs/rules/prefer-hooks-in-order.md
index f83ff9238..e3aa81805 100644
--- a/docs/rules/prefer-hooks-in-order.md
+++ b/docs/rules/prefer-hooks-in-order.md
@@ -1,5 +1,8 @@
 # Prefer having hooks in a consistent order (`prefer-hooks-in-order`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 While hooks can be setup in any order, they're always called by `jest` in this
 specific order:
 
diff --git a/docs/rules/prefer-hooks-on-top.md b/docs/rules/prefer-hooks-on-top.md
index 75e4413c7..03956a57a 100644
--- a/docs/rules/prefer-hooks-on-top.md
+++ b/docs/rules/prefer-hooks-on-top.md
@@ -1,5 +1,8 @@
 # Suggest having hooks before any test cases (`prefer-hooks-on-top`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 While hooks can be setup anywhere in a test file, they are always called in a
 specific order, which means it can be confusing if they're intermixed with test
 cases.
diff --git a/docs/rules/prefer-lowercase-title.md b/docs/rules/prefer-lowercase-title.md
index 5099fcdfe..fb4c7a77d 100644
--- a/docs/rules/prefer-lowercase-title.md
+++ b/docs/rules/prefer-lowercase-title.md
@@ -1,6 +1,12 @@
 # Enforce lowercase test names (`prefer-lowercase-title`)
 
-## Rule details
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
+## Rule Details
 
 Enforce `it`, `test` and `describe` to have descriptions that begin with a
 lowercase letter. This provides more readable test failures. This rule is not
diff --git a/docs/rules/prefer-mock-promise-shorthand.md b/docs/rules/prefer-mock-promise-shorthand.md
index f7dda79a3..f1ff9fe56 100644
--- a/docs/rules/prefer-mock-promise-shorthand.md
+++ b/docs/rules/prefer-mock-promise-shorthand.md
@@ -1,5 +1,11 @@
 # Prefer mock resolved/rejected shorthands for promises (`prefer-mock-promise-shorthand`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 When working with mocks of functions that return promises, Jest provides some
 API sugar functions to reduce the amount of boilerplate you have to write.
 
diff --git a/docs/rules/prefer-snapshot-hint.md b/docs/rules/prefer-snapshot-hint.md
index 4c4dbc515..fc4294721 100644
--- a/docs/rules/prefer-snapshot-hint.md
+++ b/docs/rules/prefer-snapshot-hint.md
@@ -1,5 +1,8 @@
 # Prefer including a hint with external snapshots (`prefer-snapshot-hint`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 When working with external snapshot matchers it's considered best practice to
 provide a hint (as the last argument to the matcher) describing the expected
 snapshot content that will be included in the snapshots name by Jest.
@@ -8,7 +11,7 @@ This makes it easier for reviewers to verify the snapshots during review, and
 for anyone to know whether an outdated snapshot is the correct behavior before
 updating.
 
-## Rule details
+## Rule Details
 
 This rule looks for any use of an external snapshot matcher (e.g.
 `toMatchSnapshot` and `toThrowErrorMatchingSnapshot`) and checks if they include
diff --git a/docs/rules/prefer-spy-on.md b/docs/rules/prefer-spy-on.md
index 25877d629..f52eb5712 100644
--- a/docs/rules/prefer-spy-on.md
+++ b/docs/rules/prefer-spy-on.md
@@ -1,5 +1,11 @@
 # Suggest using `jest.spyOn()` (`prefer-spy-on`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 When mocking a function by overwriting a property you have to manually restore
 the original implementation when cleaning up. When using `jest.spyOn()` Jest
 keeps track of changes, and they can be restored with `jest.restoreAllMocks()`,
@@ -19,7 +25,7 @@ jest.spyOn(Date, 'now').mockImplementation(() => 10); // Will always return 10
 jest.spyOn(Date, 'now').mockReturnValue(10); // Will always return 10
 ```
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if an object's property is overwritten with a jest
 mock.
diff --git a/docs/rules/prefer-strict-equal.md b/docs/rules/prefer-strict-equal.md
index 81a2b5f92..fe62ef3b4 100644
--- a/docs/rules/prefer-strict-equal.md
+++ b/docs/rules/prefer-strict-equal.md
@@ -1,11 +1,17 @@
 # Suggest using `toStrictEqual()` (`prefer-strict-equal`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
+<!-- prettier-ignore -->
+💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+
 `toStrictEqual` not only checks that two objects contain the same data but also
 that they have the same structure. It is common to expect objects to not only
 have identical values but also to have identical keys. A stricter equality will
 catch cases where two objects do not have identical keys.
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if `toEqual()` is used to assert equality.
 
diff --git a/docs/rules/prefer-to-be.md b/docs/rules/prefer-to-be.md
index 8611b42cf..130b0c90d 100644
--- a/docs/rules/prefer-to-be.md
+++ b/docs/rules/prefer-to-be.md
@@ -1,5 +1,11 @@
 # Suggest using `toBe()` for primitive literals (`prefer-to-be`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 When asserting against primitive literals such as numbers and strings, the
 equality matchers all operate the same, but read slightly differently in code.
 
@@ -8,7 +14,7 @@ the most grammatically natural sentence. For `null`, `undefined`, and `NaN` this
 rule recommends using their specific `toBe` matchers, as they give better error
 messages as well.
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if `toEqual()` or `toStrictEqual()` are used to
 assert a primitive literal value such as numbers, strings, and booleans.
diff --git a/docs/rules/prefer-to-contain.md b/docs/rules/prefer-to-contain.md
index b1144bc26..899e719f6 100644
--- a/docs/rules/prefer-to-contain.md
+++ b/docs/rules/prefer-to-contain.md
@@ -1,9 +1,15 @@
 # Suggest using `toContain()` (`prefer-to-contain`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 In order to have a better failure message, `toContain()` should be used upon
 asserting expectations on an array containing an object.
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if `toBe()`, `toEqual()` or `toStrictEqual()` is
 used to assert object inclusion in an array
diff --git a/docs/rules/prefer-to-have-length.md b/docs/rules/prefer-to-have-length.md
index d44e9e079..625170963 100644
--- a/docs/rules/prefer-to-have-length.md
+++ b/docs/rules/prefer-to-have-length.md
@@ -1,9 +1,15 @@
 # Suggest using `toHaveLength()` (`prefer-to-have-length`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 In order to have a better failure message, `toHaveLength()` should be used upon
 asserting expectations on objects length property.
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if `toBe()`, `toEqual()` or `toStrictEqual()` is
 used to assert objects length property.
diff --git a/docs/rules/prefer-todo.md b/docs/rules/prefer-todo.md
index c294cbdbf..7b22a590b 100644
--- a/docs/rules/prefer-todo.md
+++ b/docs/rules/prefer-todo.md
@@ -1,9 +1,15 @@
 # Suggest using `test.todo` (`prefer-todo`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 When test cases are empty then it is better to mark them as `test.todo` as it
 will be highlighted in the summary output.
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if empty test cases are used without 'test.todo'.
 
diff --git a/docs/rules/require-hook.md b/docs/rules/require-hook.md
index 41b83bc7f..29563d3b4 100644
--- a/docs/rules/require-hook.md
+++ b/docs/rules/require-hook.md
@@ -1,5 +1,8 @@
 # Require setup and teardown code to be within a hook (`require-hook`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 Often while writing tests you have some setup work that needs to happen before
 tests run, and you have some finishing work that needs to happen after tests
 run. Jest provides helper functions to handle this.
@@ -12,7 +15,7 @@ executes any of the actual tests, it's important to ensure setup and teardown
 work is done inside `before*` and `after*` handlers respectively, rather than
 inside the `describe` blocks.
 
-## Rule details
+## Rule Details
 
 This rule flags any expression that is either at the toplevel of a test file or
 directly within the body of a `describe`, _except_ for the following:
diff --git a/docs/rules/require-to-throw-message.md b/docs/rules/require-to-throw-message.md
index 4eea732f2..c9f6c5a17 100644
--- a/docs/rules/require-to-throw-message.md
+++ b/docs/rules/require-to-throw-message.md
@@ -1,11 +1,14 @@
 # Require a message for `toThrow()` (`require-to-throw-message`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 `toThrow()` (and its alias `toThrowError()`) is used to check if an error is
 thrown by a function call, such as in `expect(() => a()).toThrow()`. However, if
 no message is defined, then the test will pass for any thrown error. Requiring a
 message ensures that the intended error is thrown.
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if `toThrow()` or `toThrowError()` is used without
 an error message.
diff --git a/docs/rules/require-top-level-describe.md b/docs/rules/require-top-level-describe.md
index 389b8dbdb..146de24da 100644
--- a/docs/rules/require-top-level-describe.md
+++ b/docs/rules/require-top-level-describe.md
@@ -1,5 +1,8 @@
 # Require test cases and hooks to be inside a `describe` block (`require-top-level-describe`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 Jest allows you to organise your test files the way you want it. However, the
 more your codebase grows, the more it becomes hard to navigate in your test
 files. This rule makes sure you provide at least a top-level `describe` block in
@@ -47,6 +50,8 @@ describe('test suite', () => {
 });
 ```
 
+## Options
+
 You can also enforce a limit on the number of describes allowed at the top-level
 using the `maxNumberOfTopLevelDescribes` option:
 
diff --git a/docs/rules/unbound-method.md b/docs/rules/unbound-method.md
index d4bef0920..f8b25a4c7 100644
--- a/docs/rules/unbound-method.md
+++ b/docs/rules/unbound-method.md
@@ -1,5 +1,8 @@
 # Enforce unbound methods are called with their expected scope (`unbound-method`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+
 ## Rule Details
 
 This rule extends the base [`@typescript-eslint/unbound-method`][original-rule]
diff --git a/docs/rules/valid-describe-callback.md b/docs/rules/valid-describe-callback.md
index 32ef3a18e..7993660e5 100644
--- a/docs/rules/valid-describe-callback.md
+++ b/docs/rules/valid-describe-callback.md
@@ -1,5 +1,8 @@
 # Enforce valid `describe()` callback (`valid-describe-callback`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
 Using an improper `describe()` callback function can lead to unexpected test
 errors.
 
diff --git a/docs/rules/valid-expect-in-promise.md b/docs/rules/valid-expect-in-promise.md
index 03c3fb6d0..ea1b442c3 100644
--- a/docs/rules/valid-expect-in-promise.md
+++ b/docs/rules/valid-expect-in-promise.md
@@ -1,8 +1,11 @@
 # Ensure promises that have expectations in their chain are valid (`valid-expect-in-promise`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
 Ensure promises that include expectations are returned or awaited.
 
-## Rule details
+## Rule Details
 
 This rule flags any promises within the body of a test that include expectations
 that have either not been returned or awaited.
diff --git a/docs/rules/valid-expect.md b/docs/rules/valid-expect.md
index 39f0518b4..ae3b9fc17 100644
--- a/docs/rules/valid-expect.md
+++ b/docs/rules/valid-expect.md
@@ -1,9 +1,12 @@
 # Enforce valid `expect()` usage (`valid-expect`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
 Ensure `expect()` is called with a single argument and there is an actual
 expectation made.
 
-## Rule details
+## Rule Details
 
 This rule triggers a warning if `expect()` is called with more than one argument
 or without arguments. It would also issue a warning if there is nothing called
diff --git a/docs/rules/valid-title.md b/docs/rules/valid-title.md
index ab1ae76ad..261b5b6b8 100644
--- a/docs/rules/valid-title.md
+++ b/docs/rules/valid-title.md
@@ -1,5 +1,11 @@
 # Enforce valid titles (`valid-title`)
 
+<!-- prettier-ignore -->
+💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+
+<!-- prettier-ignore -->
+🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
+
 Checks that the title of Jest blocks are valid by ensuring that titles are:
 
 - not empty,
diff --git a/src/__tests__/rules.test.ts b/src/__tests__/rules.test.ts
index a8c66cc18..d53697b0c 100644
--- a/src/__tests__/rules.test.ts
+++ b/src/__tests__/rules.test.ts
@@ -1,5 +1,6 @@
-import { existsSync } from 'fs';
-import { resolve } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { EOL } from 'os';
+import { join, resolve } from 'path';
 import plugin from '../';
 
 const numberOfRules = 50;
@@ -76,4 +77,136 @@ describe('rules', () => {
       expect(() => require(`../rules/${ruleName}`)).not.toThrow();
     });
   });
+
+  describe('rule documentation files have the correct content', () => {
+    enum MESSAGE_TYPE {
+      CONFIGS = 1,
+      DEPRECATED = 2,
+      FIXABLE = 3,
+      HAS_SUGGESTIONS = 4,
+    }
+    const MESSAGES = {
+      [MESSAGE_TYPE.CONFIGS]:
+        '💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):',
+      [MESSAGE_TYPE.DEPRECATED]: '❌ This rule is deprecated.',
+      [MESSAGE_TYPE.FIXABLE]:
+        '🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.',
+      [MESSAGE_TYPE.HAS_SUGGESTIONS]:
+        '💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).',
+    };
+
+    function getConfigsForRule(ruleName: keyof typeof plugin.rules) {
+      const { configs } = plugin;
+      const configNames: Array<keyof typeof configs> = [];
+      let configName: keyof typeof configs;
+
+      for (configName in configs) {
+        const config = configs[configName];
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- we don't have a static type for rule names
+        // @ts-ignore
+        const value = config.rules[`jest/${ruleName}`];
+        const isEnabled = [2, 'error'].includes(value);
+
+        if (isEnabled) {
+          configNames.push(configName);
+        }
+      }
+
+      return configNames.sort();
+    }
+
+    function configNamesToList(configNames: string[]) {
+      return `\`${configNames.join('`, `')}\``;
+    }
+
+    it.each(ruleNames)('%s', ruleName => {
+      const rule = plugin.rules[ruleName];
+      const documentPath = join('docs', 'rules', `${ruleName}.md`);
+      const documentContents = readFileSync(documentPath, 'utf8');
+      const documentLines = documentContents.split(EOL);
+
+      // Check title.
+      const expectedTitle = `# ${rule.meta.docs.description} (\`${ruleName}\`)`;
+
+      expect(documentLines[0]).toStrictEqual(expectedTitle); // Includes the rule description and name in title.
+
+      // Decide which notices should be shown at the top of the doc.
+      const expectedNotices: MESSAGE_TYPE[] = [];
+      const unexpectedNotices: MESSAGE_TYPE[] = [];
+
+      if (rule.meta.deprecated) {
+        expectedNotices.push(MESSAGE_TYPE.DEPRECATED);
+        unexpectedNotices.push(MESSAGE_TYPE.CONFIGS);
+      } else {
+        unexpectedNotices.push(MESSAGE_TYPE.DEPRECATED);
+        expectedNotices.push(MESSAGE_TYPE.CONFIGS);
+      }
+      if (rule.meta.fixable) {
+        expectedNotices.push(MESSAGE_TYPE.FIXABLE);
+      } else {
+        unexpectedNotices.push(MESSAGE_TYPE.FIXABLE);
+      }
+      if (rule.meta.hasSuggestions) {
+        expectedNotices.push(MESSAGE_TYPE.HAS_SUGGESTIONS);
+      } else {
+        unexpectedNotices.push(MESSAGE_TYPE.HAS_SUGGESTIONS);
+      }
+
+      // Ensure that expected notices are present in the correct order.
+      let currentLineNumber = 1;
+
+      expectedNotices.forEach(expectedNotice => {
+        expect(documentLines[currentLineNumber]).toStrictEqual(''); // Blank line first.
+
+        if (
+          documentLines[currentLineNumber + 1] === '<!-- prettier-ignore -->'
+        ) {
+          // Ignore any Prettier ignore comment that may be needed so that the notice doesn't get split onto multiple lines.
+          currentLineNumber++;
+        }
+
+        if (expectedNotice === MESSAGE_TYPE.CONFIGS) {
+          // Check that the rule has a notice with a list of its configs.
+          const configsEnabled = getConfigsForRule(ruleName);
+          const expectedMessage = `${
+            MESSAGES[MESSAGE_TYPE.CONFIGS]
+          } ${configNamesToList(configsEnabled)}.`;
+
+          expect(documentLines[currentLineNumber + 1]).toStrictEqual(
+            expectedMessage,
+          );
+        } else {
+          // For other notice types, just check the whole line.
+          expect(documentLines[currentLineNumber + 1]).toStrictEqual(
+            MESSAGES[expectedNotice],
+          );
+        }
+        currentLineNumber += 2;
+      });
+
+      // Ensure that unexpected notices are not present.
+      unexpectedNotices.forEach(unexpectedNotice => {
+        expect(
+          documentContents.includes(MESSAGES[unexpectedNotice]),
+        ).toStrictEqual(false);
+      });
+
+      // Check for Rule Details section.
+      expect(documentContents).toContain('## Rule Details');
+
+      // Check if the rule has configuration options.
+      if (
+        (Array.isArray(rule.meta.schema) && rule.meta.schema.length > 0) ||
+        (typeof rule.meta.schema === 'object' &&
+          Object.keys(rule.meta.schema).length > 0)
+      ) {
+        // Should have an options section header:
+        expect(documentContents).toContain('## Options');
+      } else {
+        // Should NOT have any options section header:
+        expect(documentContents.includes('## Options')).toStrictEqual(false);
+        expect(documentContents.includes('## Config')).toStrictEqual(false);
+      }
+    });
+  });
 });

From 67273013ee892c1478d1ebcf4bb9e6f6aa6ccd99 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Fri, 2 Sep 2022 11:32:20 -0700
Subject: [PATCH 02/23] docs: switch to automatic rule notice generation

---
 README.md                                   |   2 +
 docs/rules/consistent-test-it.md            |   4 +
 docs/rules/expect-expect.md                 |   4 +
 docs/rules/max-expects.md                   |   4 +
 docs/rules/max-nested-describe.md           |   4 +
 docs/rules/no-alias-methods.md              |   4 +
 docs/rules/no-commented-out-tests.md        |   4 +
 docs/rules/no-conditional-expect.md         |   4 +
 docs/rules/no-conditional-in-test.md        |   4 +
 docs/rules/no-deprecated-functions.md       |   4 +
 docs/rules/no-disabled-tests.md             |   4 +
 docs/rules/no-done-callback.md              |   4 +
 docs/rules/no-duplicate-hooks.md            |   4 +
 docs/rules/no-export.md                     |   4 +
 docs/rules/no-focused-tests.md              |   5 +
 docs/rules/no-hooks.md                      |   4 +
 docs/rules/no-identical-title.md            |   4 +
 docs/rules/no-if.md                         |   4 +
 docs/rules/no-interpolation-in-snapshots.md |   4 +
 docs/rules/no-jasmine-globals.md            |   4 +
 docs/rules/no-large-snapshots.md            |   4 +
 docs/rules/no-mocks-import.md               |   4 +
 docs/rules/no-restricted-matchers.md        |   4 +
 docs/rules/no-standalone-expect.md          |   4 +
 docs/rules/no-test-prefixes.md              |   4 +
 docs/rules/no-test-return-statement.md      |   4 +
 docs/rules/prefer-called-with.md            |   4 +
 docs/rules/prefer-comparison-matcher.md     |   4 +
 docs/rules/prefer-each.md                   |   4 +
 docs/rules/prefer-equality-matcher.md       |   4 +
 docs/rules/prefer-expect-assertions.md      |   4 +
 docs/rules/prefer-expect-resolves.md        |   4 +
 docs/rules/prefer-hooks-in-order.md         |   4 +
 docs/rules/prefer-hooks-on-top.md           |   4 +
 docs/rules/prefer-lowercase-title.md        |   4 +
 docs/rules/prefer-mock-promise-shorthand.md |   4 +
 docs/rules/prefer-snapshot-hint.md          |   4 +
 docs/rules/prefer-spy-on.md                 |   4 +
 docs/rules/prefer-strict-equal.md           |   4 +
 docs/rules/prefer-to-be.md                  |   4 +
 docs/rules/prefer-to-contain.md             |   4 +
 docs/rules/prefer-to-have-length.md         |   4 +
 docs/rules/prefer-todo.md                   |   4 +
 docs/rules/require-hook.md                  |   4 +
 docs/rules/require-to-throw-message.md      |   4 +
 docs/rules/require-top-level-describe.md    |   4 +
 docs/rules/unbound-method.md                |   4 +
 docs/rules/valid-describe-callback.md       |   4 +
 docs/rules/valid-expect-in-promise.md       |   4 +
 docs/rules/valid-expect.md                  |   4 +
 docs/rules/valid-title.md                   |   4 +
 src/__tests__/rules.test.ts                 | 109 +++----------------
 tools/regenerate-docs.ts                    |  49 ++++++++-
 tools/rule-notices.ts                       | 115 ++++++++++++++++++++
 54 files changed, 377 insertions(+), 99 deletions(-)
 create mode 100644 tools/rule-notices.ts

diff --git a/README.md b/README.md
index d1093295e..a53b4556f 100644
--- a/README.md
+++ b/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
diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md
index 881073c9c..713da2fb9 100644
--- a/docs/rules/consistent-test-it.md
+++ b/docs/rules/consistent-test-it.md
@@ -1,11 +1,15 @@
 # Have control over `test` and `it` usages (`consistent-test-it`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 Jest allows you to choose how you want to define your tests, using the `it` or
 the `test` keywords, with multiple permutations for each:
 
diff --git a/docs/rules/expect-expect.md b/docs/rules/expect-expect.md
index c9747ea61..22347da47 100644
--- a/docs/rules/expect-expect.md
+++ b/docs/rules/expect-expect.md
@@ -1,8 +1,12 @@
 # Enforce assertion to be made in a test body (`expect-expect`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 Ensure that there is at least one `expect` call made in a test.
 
 ## Rule Details
diff --git a/docs/rules/max-expects.md b/docs/rules/max-expects.md
index d5fa1f752..fe9175101 100644
--- a/docs/rules/max-expects.md
+++ b/docs/rules/max-expects.md
@@ -1,8 +1,12 @@
 # Enforces a maximum number assertion calls in a test body (`max-expects`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 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.
diff --git a/docs/rules/max-nested-describe.md b/docs/rules/max-nested-describe.md
index 0fc83553c..dbff28fd5 100644
--- a/docs/rules/max-nested-describe.md
+++ b/docs/rules/max-nested-describe.md
@@ -1,8 +1,12 @@
 # Enforces a maximum depth to nested describe calls (`max-nested-describe`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 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.
diff --git a/docs/rules/no-alias-methods.md b/docs/rules/no-alias-methods.md
index 341151124..541041d10 100644
--- a/docs/rules/no-alias-methods.md
+++ b/docs/rules/no-alias-methods.md
@@ -1,11 +1,15 @@
 # Disallow alias methods (`no-alias-methods`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 > These aliases are going to be removed in the next major version of Jest - see
 > https://github.com/facebook/jest/issues/13164 for more
 
diff --git a/docs/rules/no-commented-out-tests.md b/docs/rules/no-commented-out-tests.md
index adce60fed..ba17dc838 100644
--- a/docs/rules/no-commented-out-tests.md
+++ b/docs/rules/no-commented-out-tests.md
@@ -1,8 +1,12 @@
 # Disallow commented out tests (`no-commented-out-tests`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 This rule raises a warning about commented out tests. It's similar to
 no-disabled-tests rule.
 
diff --git a/docs/rules/no-conditional-expect.md b/docs/rules/no-conditional-expect.md
index 14d5ae6c3..a51212cb0 100644
--- a/docs/rules/no-conditional-expect.md
+++ b/docs/rules/no-conditional-expect.md
@@ -1,8 +1,12 @@
 # Prevent calling `expect` conditionally (`no-conditional-expect`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
+<!-- /RULE_NOTICE -->
+
 This rule prevents the use of `expect` in conditional blocks, such as `if`s &
 `catch`s.
 
diff --git a/docs/rules/no-conditional-in-test.md b/docs/rules/no-conditional-in-test.md
index 073724019..06e6bf12c 100644
--- a/docs/rules/no-conditional-in-test.md
+++ b/docs/rules/no-conditional-in-test.md
@@ -1,8 +1,12 @@
 # Disallow conditional logic in tests (`no-conditional-in-test`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 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
diff --git a/docs/rules/no-deprecated-functions.md b/docs/rules/no-deprecated-functions.md
index 8f21028fe..f3258d8cc 100644
--- a/docs/rules/no-deprecated-functions.md
+++ b/docs/rules/no-deprecated-functions.md
@@ -1,11 +1,15 @@
 # Disallow use of deprecated functions (`no-deprecated-functions`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 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.
 
diff --git a/docs/rules/no-disabled-tests.md b/docs/rules/no-disabled-tests.md
index 1e08ff1ac..8e2706a65 100644
--- a/docs/rules/no-disabled-tests.md
+++ b/docs/rules/no-disabled-tests.md
@@ -1,8 +1,12 @@
 # Disallow disabled tests (`no-disabled-tests`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 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
diff --git a/docs/rules/no-done-callback.md b/docs/rules/no-done-callback.md
index 9c4bfe4c5..e063e1a0c 100644
--- a/docs/rules/no-done-callback.md
+++ b/docs/rules/no-done-callback.md
@@ -1,11 +1,15 @@
 # Avoid using a callback in asynchronous tests and hooks (`no-done-callback`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
 <!-- prettier-ignore -->
 💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
 
+<!-- /RULE_NOTICE -->
+
 When calling asynchronous code in hooks and tests, `jest` needs to know when the
 asynchronous work is complete to progress the current run.
 
diff --git a/docs/rules/no-duplicate-hooks.md b/docs/rules/no-duplicate-hooks.md
index 78397e354..6130cd5a9 100644
--- a/docs/rules/no-duplicate-hooks.md
+++ b/docs/rules/no-duplicate-hooks.md
@@ -1,8 +1,12 @@
 # Disallow duplicate setup and teardown hooks (`no-duplicate-hooks`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 A `describe` block should not contain duplicate hooks.
 
 ## Rule Details
diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md
index b3b29d2d4..8200764d8 100644
--- a/docs/rules/no-export.md
+++ b/docs/rules/no-export.md
@@ -1,8 +1,12 @@
 # Disallow using `exports` in files containing tests (`no-export`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
+<!-- /RULE_NOTICE -->
+
 Prevents using `exports` if a file has one or more tests in it.
 
 ## Rule Details
diff --git a/docs/rules/no-focused-tests.md b/docs/rules/no-focused-tests.md
index 456c09596..4131ed93e 100644
--- a/docs/rules/no-focused-tests.md
+++ b/docs/rules/no-focused-tests.md
@@ -1,11 +1,16 @@
 # Disallow focused tests (`no-focused-tests`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
 <!-- prettier-ignore -->
 💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
 
+<!-- /RULE_NOTICE -->
+
+<!-- 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
diff --git a/docs/rules/no-hooks.md b/docs/rules/no-hooks.md
index 11f040158..cd953f10a 100644
--- a/docs/rules/no-hooks.md
+++ b/docs/rules/no-hooks.md
@@ -1,8 +1,12 @@
 # Disallow setup and teardown hooks (`no-hooks`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 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.
diff --git a/docs/rules/no-identical-title.md b/docs/rules/no-identical-title.md
index ee9b88e41..c62e589fc 100644
--- a/docs/rules/no-identical-title.md
+++ b/docs/rules/no-identical-title.md
@@ -1,8 +1,12 @@
 # Disallow identical titles (`no-identical-title`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
+<!-- /RULE_NOTICE -->
+
 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
diff --git a/docs/rules/no-if.md b/docs/rules/no-if.md
index b03a066e0..0e3c61fba 100644
--- a/docs/rules/no-if.md
+++ b/docs/rules/no-if.md
@@ -1,7 +1,11 @@
 # Disallow conditional logic (`no-if`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 ❌ This rule is deprecated.
 
+<!-- /RULE_NOTICE -->
+
 This rule has been deprecated in favor of
 [`no-conditional-in-test`](no-conditional-in-test.md).
 
diff --git a/docs/rules/no-interpolation-in-snapshots.md b/docs/rules/no-interpolation-in-snapshots.md
index 128e07258..0539a42ff 100644
--- a/docs/rules/no-interpolation-in-snapshots.md
+++ b/docs/rules/no-interpolation-in-snapshots.md
@@ -1,8 +1,12 @@
 # Disallow string interpolation inside snapshots (`no-interpolation-in-snapshots`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
+<!-- /RULE_NOTICE -->
+
 Prevents the use of string interpolations in snapshots.
 
 ## Rule Details
diff --git a/docs/rules/no-jasmine-globals.md b/docs/rules/no-jasmine-globals.md
index 299e11e3c..950b66e32 100644
--- a/docs/rules/no-jasmine-globals.md
+++ b/docs/rules/no-jasmine-globals.md
@@ -1,11 +1,15 @@
 # Disallow Jasmine globals (`no-jasmine-globals`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 `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
diff --git a/docs/rules/no-large-snapshots.md b/docs/rules/no-large-snapshots.md
index 0c2416ef8..2b0c2c7f8 100644
--- a/docs/rules/no-large-snapshots.md
+++ b/docs/rules/no-large-snapshots.md
@@ -1,8 +1,12 @@
 # disallow large snapshots (`no-large-snapshots`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 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
diff --git a/docs/rules/no-mocks-import.md b/docs/rules/no-mocks-import.md
index 483ee7851..54be7133b 100644
--- a/docs/rules/no-mocks-import.md
+++ b/docs/rules/no-mocks-import.md
@@ -1,8 +1,12 @@
 # Disallow manually importing from `__mocks__` (`no-mocks-import`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
+<!-- /RULE_NOTICE -->
+
 When using `jest.mock`, your tests (just like the code being tested) should
 import from `./x`, not `./__mocks__/x`. Not following this rule can lead to
 confusion, because you will have multiple instances of the mocked module:
diff --git a/docs/rules/no-restricted-matchers.md b/docs/rules/no-restricted-matchers.md
index 844d308fe..03573ad4e 100644
--- a/docs/rules/no-restricted-matchers.md
+++ b/docs/rules/no-restricted-matchers.md
@@ -1,8 +1,12 @@
 # Disallow specific matchers & modifiers (`no-restricted-matchers`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 You may want to ban specific matchers & modifiers from being used.
 
 ## Rule Details
diff --git a/docs/rules/no-standalone-expect.md b/docs/rules/no-standalone-expect.md
index 36cbf5221..d221d3b43 100644
--- a/docs/rules/no-standalone-expect.md
+++ b/docs/rules/no-standalone-expect.md
@@ -1,8 +1,12 @@
 # Disallow using `expect` outside of `it` or `test` blocks (`no-standalone-expect`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
+<!-- /RULE_NOTICE -->
+
 Prevents `expect` statements outside of a `test` or `it` block. An `expect`
 within a helper function (but outside of a `test` or `it` block) will not
 trigger this rule.
diff --git a/docs/rules/no-test-prefixes.md b/docs/rules/no-test-prefixes.md
index 65405f8b7..ab1581826 100644
--- a/docs/rules/no-test-prefixes.md
+++ b/docs/rules/no-test-prefixes.md
@@ -1,11 +1,15 @@
 # Use `.only` and `.skip` over `f` and `x` (`no-test-prefixes`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 Jest allows you to choose how you want to define focused and skipped tests, with
 multiple permutations for each:
 
diff --git a/docs/rules/no-test-return-statement.md b/docs/rules/no-test-return-statement.md
index e3f7a3694..b744eaed1 100644
--- a/docs/rules/no-test-return-statement.md
+++ b/docs/rules/no-test-return-statement.md
@@ -1,8 +1,12 @@
 # Disallow explicitly returning from tests (`no-test-return-statement`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 Tests in Jest should be void and not return values.
 
 If you are returning Promises then you should update the test to use
diff --git a/docs/rules/prefer-called-with.md b/docs/rules/prefer-called-with.md
index f38eda7e7..1753ae27b 100644
--- a/docs/rules/prefer-called-with.md
+++ b/docs/rules/prefer-called-with.md
@@ -1,8 +1,12 @@
 # Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` (`prefer-called-with`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 The `toBeCalled()` matcher is used to assert that a mock function has been
 called one or more times, without checking the arguments passed. The assertion
 is stronger when arguments are also validated using the `toBeCalledWith()`
diff --git a/docs/rules/prefer-comparison-matcher.md b/docs/rules/prefer-comparison-matcher.md
index 3757d8340..a9199eabe 100644
--- a/docs/rules/prefer-comparison-matcher.md
+++ b/docs/rules/prefer-comparison-matcher.md
@@ -1,11 +1,15 @@
 # Suggest using the built-in comparison matchers (`prefer-comparison-matcher`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 Jest has a number of built-in matchers for comparing numbers, which allow for
 more readable tests and error messages if an expectation fails.
 
diff --git a/docs/rules/prefer-each.md b/docs/rules/prefer-each.md
index 4d42b9060..fa6ab8e2f 100644
--- a/docs/rules/prefer-each.md
+++ b/docs/rules/prefer-each.md
@@ -1,8 +1,12 @@
 # Prefer using `.each` rather than manual loops (`prefer-each`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 Reports where you might be able to use `.each` instead of native loops.
 
 ## Rule Details
diff --git a/docs/rules/prefer-equality-matcher.md b/docs/rules/prefer-equality-matcher.md
index 938ad3f8e..c2d0f1ace 100644
--- a/docs/rules/prefer-equality-matcher.md
+++ b/docs/rules/prefer-equality-matcher.md
@@ -1,11 +1,15 @@
 # Suggest using the built-in equality matchers (`prefer-equality-matcher`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
 <!-- prettier-ignore -->
 💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
 
+<!-- /RULE_NOTICE -->
+
 Jest has built-in matchers for expecting equality, which allow for more readable
 tests and error messages if an expectation fails.
 
diff --git a/docs/rules/prefer-expect-assertions.md b/docs/rules/prefer-expect-assertions.md
index 2638368c1..2b2194947 100644
--- a/docs/rules/prefer-expect-assertions.md
+++ b/docs/rules/prefer-expect-assertions.md
@@ -1,11 +1,15 @@
 # Suggest using `expect.assertions()` OR `expect.hasAssertions()` (`prefer-expect-assertions`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
 <!-- prettier-ignore -->
 💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
 
+<!-- /RULE_NOTICE -->
+
 Ensure every test to have either `expect.assertions(<number of assertions>)` OR
 `expect.hasAssertions()` as its first expression.
 
diff --git a/docs/rules/prefer-expect-resolves.md b/docs/rules/prefer-expect-resolves.md
index f5f633f30..c01dc46f3 100644
--- a/docs/rules/prefer-expect-resolves.md
+++ b/docs/rules/prefer-expect-resolves.md
@@ -1,11 +1,15 @@
 # Prefer `await expect(...).resolves` over `expect(await ...)` syntax (`prefer-expect-resolves`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 When working with promises, there are two primary ways you can test the resolved
 value:
 
diff --git a/docs/rules/prefer-hooks-in-order.md b/docs/rules/prefer-hooks-in-order.md
index e3aa81805..10f9d338a 100644
--- a/docs/rules/prefer-hooks-in-order.md
+++ b/docs/rules/prefer-hooks-in-order.md
@@ -1,8 +1,12 @@
 # Prefer having hooks in a consistent order (`prefer-hooks-in-order`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 While hooks can be setup in any order, they're always called by `jest` in this
 specific order:
 
diff --git a/docs/rules/prefer-hooks-on-top.md b/docs/rules/prefer-hooks-on-top.md
index 03956a57a..aa3f636f7 100644
--- a/docs/rules/prefer-hooks-on-top.md
+++ b/docs/rules/prefer-hooks-on-top.md
@@ -1,8 +1,12 @@
 # Suggest having hooks before any test cases (`prefer-hooks-on-top`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 While hooks can be setup anywhere in a test file, they are always called in a
 specific order, which means it can be confusing if they're intermixed with test
 cases.
diff --git a/docs/rules/prefer-lowercase-title.md b/docs/rules/prefer-lowercase-title.md
index fb4c7a77d..2f45edbcc 100644
--- a/docs/rules/prefer-lowercase-title.md
+++ b/docs/rules/prefer-lowercase-title.md
@@ -1,11 +1,15 @@
 # Enforce lowercase test names (`prefer-lowercase-title`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 ## Rule Details
 
 Enforce `it`, `test` and `describe` to have descriptions that begin with a
diff --git a/docs/rules/prefer-mock-promise-shorthand.md b/docs/rules/prefer-mock-promise-shorthand.md
index f1ff9fe56..05287bdfb 100644
--- a/docs/rules/prefer-mock-promise-shorthand.md
+++ b/docs/rules/prefer-mock-promise-shorthand.md
@@ -1,11 +1,15 @@
 # Prefer mock resolved/rejected shorthands for promises (`prefer-mock-promise-shorthand`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 When working with mocks of functions that return promises, Jest provides some
 API sugar functions to reduce the amount of boilerplate you have to write.
 
diff --git a/docs/rules/prefer-snapshot-hint.md b/docs/rules/prefer-snapshot-hint.md
index fc4294721..e5fe86f10 100644
--- a/docs/rules/prefer-snapshot-hint.md
+++ b/docs/rules/prefer-snapshot-hint.md
@@ -1,8 +1,12 @@
 # Prefer including a hint with external snapshots (`prefer-snapshot-hint`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 When working with external snapshot matchers it's considered best practice to
 provide a hint (as the last argument to the matcher) describing the expected
 snapshot content that will be included in the snapshots name by Jest.
diff --git a/docs/rules/prefer-spy-on.md b/docs/rules/prefer-spy-on.md
index f52eb5712..4896e4e95 100644
--- a/docs/rules/prefer-spy-on.md
+++ b/docs/rules/prefer-spy-on.md
@@ -1,11 +1,15 @@
 # Suggest using `jest.spyOn()` (`prefer-spy-on`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 When mocking a function by overwriting a property you have to manually restore
 the original implementation when cleaning up. When using `jest.spyOn()` Jest
 keeps track of changes, and they can be restored with `jest.restoreAllMocks()`,
diff --git a/docs/rules/prefer-strict-equal.md b/docs/rules/prefer-strict-equal.md
index fe62ef3b4..8ad042472 100644
--- a/docs/rules/prefer-strict-equal.md
+++ b/docs/rules/prefer-strict-equal.md
@@ -1,11 +1,15 @@
 # Suggest using `toStrictEqual()` (`prefer-strict-equal`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
 <!-- prettier-ignore -->
 💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
 
+<!-- /RULE_NOTICE -->
+
 `toStrictEqual` not only checks that two objects contain the same data but also
 that they have the same structure. It is common to expect objects to not only
 have identical values but also to have identical keys. A stricter equality will
diff --git a/docs/rules/prefer-to-be.md b/docs/rules/prefer-to-be.md
index 130b0c90d..1b6043843 100644
--- a/docs/rules/prefer-to-be.md
+++ b/docs/rules/prefer-to-be.md
@@ -1,11 +1,15 @@
 # Suggest using `toBe()` for primitive literals (`prefer-to-be`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 When asserting against primitive literals such as numbers and strings, the
 equality matchers all operate the same, but read slightly differently in code.
 
diff --git a/docs/rules/prefer-to-contain.md b/docs/rules/prefer-to-contain.md
index 899e719f6..37d2465ba 100644
--- a/docs/rules/prefer-to-contain.md
+++ b/docs/rules/prefer-to-contain.md
@@ -1,11 +1,15 @@
 # Suggest using `toContain()` (`prefer-to-contain`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 In order to have a better failure message, `toContain()` should be used upon
 asserting expectations on an array containing an object.
 
diff --git a/docs/rules/prefer-to-have-length.md b/docs/rules/prefer-to-have-length.md
index 625170963..f480fad9f 100644
--- a/docs/rules/prefer-to-have-length.md
+++ b/docs/rules/prefer-to-have-length.md
@@ -1,11 +1,15 @@
 # Suggest using `toHaveLength()` (`prefer-to-have-length`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 In order to have a better failure message, `toHaveLength()` should be used upon
 asserting expectations on objects length property.
 
diff --git a/docs/rules/prefer-todo.md b/docs/rules/prefer-todo.md
index 7b22a590b..959911572 100644
--- a/docs/rules/prefer-todo.md
+++ b/docs/rules/prefer-todo.md
@@ -1,11 +1,15 @@
 # Suggest using `test.todo` (`prefer-todo`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 When test cases are empty then it is better to mark them as `test.todo` as it
 will be highlighted in the summary output.
 
diff --git a/docs/rules/require-hook.md b/docs/rules/require-hook.md
index 29563d3b4..e56036cb7 100644
--- a/docs/rules/require-hook.md
+++ b/docs/rules/require-hook.md
@@ -1,8 +1,12 @@
 # Require setup and teardown code to be within a hook (`require-hook`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 Often while writing tests you have some setup work that needs to happen before
 tests run, and you have some finishing work that needs to happen after tests
 run. Jest provides helper functions to handle this.
diff --git a/docs/rules/require-to-throw-message.md b/docs/rules/require-to-throw-message.md
index c9f6c5a17..ec1f59cd0 100644
--- a/docs/rules/require-to-throw-message.md
+++ b/docs/rules/require-to-throw-message.md
@@ -1,8 +1,12 @@
 # Require a message for `toThrow()` (`require-to-throw-message`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 `toThrow()` (and its alias `toThrowError()`) is used to check if an error is
 thrown by a function call, such as in `expect(() => a()).toThrow()`. However, if
 no message is defined, then the test will pass for any thrown error. Requiring a
diff --git a/docs/rules/require-top-level-describe.md b/docs/rules/require-top-level-describe.md
index 146de24da..c9d310c8c 100644
--- a/docs/rules/require-top-level-describe.md
+++ b/docs/rules/require-top-level-describe.md
@@ -1,8 +1,12 @@
 # Require test cases and hooks to be inside a `describe` block (`require-top-level-describe`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 Jest allows you to organise your test files the way you want it. However, the
 more your codebase grows, the more it becomes hard to navigate in your test
 files. This rule makes sure you provide at least a top-level `describe` block in
diff --git a/docs/rules/unbound-method.md b/docs/rules/unbound-method.md
index f8b25a4c7..a562ff29a 100644
--- a/docs/rules/unbound-method.md
+++ b/docs/rules/unbound-method.md
@@ -1,8 +1,12 @@
 # Enforce unbound methods are called with their expected scope (`unbound-method`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
+<!-- /RULE_NOTICE -->
+
 ## Rule Details
 
 This rule extends the base [`@typescript-eslint/unbound-method`][original-rule]
diff --git a/docs/rules/valid-describe-callback.md b/docs/rules/valid-describe-callback.md
index 7993660e5..1fca6fcb7 100644
--- a/docs/rules/valid-describe-callback.md
+++ b/docs/rules/valid-describe-callback.md
@@ -1,8 +1,12 @@
 # Enforce valid `describe()` callback (`valid-describe-callback`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
+<!-- /RULE_NOTICE -->
+
 Using an improper `describe()` callback function can lead to unexpected test
 errors.
 
diff --git a/docs/rules/valid-expect-in-promise.md b/docs/rules/valid-expect-in-promise.md
index ea1b442c3..4f4ea86e0 100644
--- a/docs/rules/valid-expect-in-promise.md
+++ b/docs/rules/valid-expect-in-promise.md
@@ -1,8 +1,12 @@
 # Ensure promises that have expectations in their chain are valid (`valid-expect-in-promise`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
+<!-- /RULE_NOTICE -->
+
 Ensure promises that include expectations are returned or awaited.
 
 ## Rule Details
diff --git a/docs/rules/valid-expect.md b/docs/rules/valid-expect.md
index ae3b9fc17..46bfc9e43 100644
--- a/docs/rules/valid-expect.md
+++ b/docs/rules/valid-expect.md
@@ -1,8 +1,12 @@
 # Enforce valid `expect()` usage (`valid-expect`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
+<!-- /RULE_NOTICE -->
+
 Ensure `expect()` is called with a single argument and there is an actual
 expectation made.
 
diff --git a/docs/rules/valid-title.md b/docs/rules/valid-title.md
index 261b5b6b8..a6027ecaf 100644
--- a/docs/rules/valid-title.md
+++ b/docs/rules/valid-title.md
@@ -1,11 +1,15 @@
 # Enforce valid titles (`valid-title`)
 
+<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
+<!-- /RULE_NOTICE -->
+
 Checks that the title of Jest blocks are valid by ensuring that titles are:
 
 - not empty,
diff --git a/src/__tests__/rules.test.ts b/src/__tests__/rules.test.ts
index d53697b0c..2a39916d8 100644
--- a/src/__tests__/rules.test.ts
+++ b/src/__tests__/rules.test.ts
@@ -2,6 +2,11 @@ import { existsSync, readFileSync } from 'fs';
 import { EOL } from 'os';
 import { join, resolve } from 'path';
 import plugin from '../';
+import {
+  MESSAGES,
+  getNoticesForRule,
+  getRuleNoticeLines,
+} from '../../tools/rule-notices';
 
 const numberOfRules = 50;
 const ruleNames = Object.keys(plugin.rules);
@@ -79,46 +84,6 @@ describe('rules', () => {
   });
 
   describe('rule documentation files have the correct content', () => {
-    enum MESSAGE_TYPE {
-      CONFIGS = 1,
-      DEPRECATED = 2,
-      FIXABLE = 3,
-      HAS_SUGGESTIONS = 4,
-    }
-    const MESSAGES = {
-      [MESSAGE_TYPE.CONFIGS]:
-        '💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):',
-      [MESSAGE_TYPE.DEPRECATED]: '❌ This rule is deprecated.',
-      [MESSAGE_TYPE.FIXABLE]:
-        '🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.',
-      [MESSAGE_TYPE.HAS_SUGGESTIONS]:
-        '💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).',
-    };
-
-    function getConfigsForRule(ruleName: keyof typeof plugin.rules) {
-      const { configs } = plugin;
-      const configNames: Array<keyof typeof configs> = [];
-      let configName: keyof typeof configs;
-
-      for (configName in configs) {
-        const config = configs[configName];
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- we don't have a static type for rule names
-        // @ts-ignore
-        const value = config.rules[`jest/${ruleName}`];
-        const isEnabled = [2, 'error'].includes(value);
-
-        if (isEnabled) {
-          configNames.push(configName);
-        }
-      }
-
-      return configNames.sort();
-    }
-
-    function configNamesToList(configNames: string[]) {
-      return `\`${configNames.join('`, `')}\``;
-    }
-
     it.each(ruleNames)('%s', ruleName => {
       const rule = plugin.rules[ruleName];
       const documentPath = join('docs', 'rules', `${ruleName}.md`);
@@ -128,63 +93,21 @@ describe('rules', () => {
       // Check title.
       const expectedTitle = `# ${rule.meta.docs.description} (\`${ruleName}\`)`;
 
-      expect(documentLines[0]).toStrictEqual(expectedTitle); // Includes the rule description and name in title.
-
-      // Decide which notices should be shown at the top of the doc.
-      const expectedNotices: MESSAGE_TYPE[] = [];
-      const unexpectedNotices: MESSAGE_TYPE[] = [];
-
-      if (rule.meta.deprecated) {
-        expectedNotices.push(MESSAGE_TYPE.DEPRECATED);
-        unexpectedNotices.push(MESSAGE_TYPE.CONFIGS);
-      } else {
-        unexpectedNotices.push(MESSAGE_TYPE.DEPRECATED);
-        expectedNotices.push(MESSAGE_TYPE.CONFIGS);
-      }
-      if (rule.meta.fixable) {
-        expectedNotices.push(MESSAGE_TYPE.FIXABLE);
-      } else {
-        unexpectedNotices.push(MESSAGE_TYPE.FIXABLE);
-      }
-      if (rule.meta.hasSuggestions) {
-        expectedNotices.push(MESSAGE_TYPE.HAS_SUGGESTIONS);
-      } else {
-        unexpectedNotices.push(MESSAGE_TYPE.HAS_SUGGESTIONS);
-      }
+      expect(documentLines[0]).toStrictEqual(expectedTitle);
 
       // Ensure that expected notices are present in the correct order.
-      let currentLineNumber = 1;
-
-      expectedNotices.forEach(expectedNotice => {
-        expect(documentLines[currentLineNumber]).toStrictEqual(''); // Blank line first.
-
-        if (
-          documentLines[currentLineNumber + 1] === '<!-- prettier-ignore -->'
-        ) {
-          // Ignore any Prettier ignore comment that may be needed so that the notice doesn't get split onto multiple lines.
-          currentLineNumber++;
-        }
-
-        if (expectedNotice === MESSAGE_TYPE.CONFIGS) {
-          // Check that the rule has a notice with a list of its configs.
-          const configsEnabled = getConfigsForRule(ruleName);
-          const expectedMessage = `${
-            MESSAGES[MESSAGE_TYPE.CONFIGS]
-          } ${configNamesToList(configsEnabled)}.`;
-
-          expect(documentLines[currentLineNumber + 1]).toStrictEqual(
-            expectedMessage,
-          );
-        } else {
-          // For other notice types, just check the whole line.
-          expect(documentLines[currentLineNumber + 1]).toStrictEqual(
-            MESSAGES[expectedNotice],
-          );
-        }
-        currentLineNumber += 2;
-      });
+      const noticeLines = getRuleNoticeLines(ruleName);
+      const NOTICE_START_LINE = 3;
+
+      noticeLines.forEach((noticeLine, index) =>
+        expect(documentLines[index + NOTICE_START_LINE]).toStrictEqual(
+          noticeLine,
+        ),
+      );
 
       // Ensure that unexpected notices are not present.
+      const { unexpectedNotices } = getNoticesForRule(rule);
+
       unexpectedNotices.forEach(unexpectedNotice => {
         expect(
           documentContents.includes(MESSAGES[unexpectedNotice]),
diff --git a/tools/regenerate-docs.ts b/tools/regenerate-docs.ts
index 4f404da04..8cfcd6d01 100644
--- a/tools/regenerate-docs.ts
+++ b/tools/regenerate-docs.ts
@@ -5,7 +5,12 @@ import * as path from 'path';
 import { TSESLint } from '@typescript-eslint/utils';
 import prettier, { Options } from 'prettier';
 import { prettier as prettierRC } from '../package.json';
-import config from '../src/index';
+import plugin from '../src/index';
+import {
+  RULE_NOTICE_MARK_END,
+  RULE_NOTICE_MARK_START,
+  getRuleNoticeLines,
+} from './rule-notices';
 
 const pathTo = {
   readme: path.resolve(__dirname, '../README.md'),
@@ -23,6 +28,7 @@ interface RuleDetails {
   description: string;
   fixable: FixType | false;
   requiresTypeChecking: boolean;
+  deprecated: boolean;
 }
 
 type RuleModule = TSESLint.RuleModule<string, unknown[]> & {
@@ -35,14 +41,18 @@ const staticElements = {
 };
 
 const getConfigurationColumnValueForRule = (rule: RuleDetails): string => {
-  if (`jest/${rule.name}` in config.configs.recommended.rules) {
+  if (`jest/${rule.name}` in plugin.configs.recommended.rules) {
     return '![recommended][]';
   }
 
-  if (`jest/${rule.name}` in config.configs.style.rules) {
+  if (`jest/${rule.name}` in plugin.configs.style.rules) {
     return '![style][]';
   }
 
+  if (rule.deprecated) {
+    return '![deprecated][]';
+  }
+
   return '';
 };
 
@@ -89,6 +99,30 @@ const updateRulesList = (
   ].join('\n');
 };
 
+const updateRuleNotices = (contents, ruleName) => {
+  // Determine where to insert rule notices.
+  let ruleNoticeMarkStartLine = contents.findIndex(
+    line => line === RULE_NOTICE_MARK_START,
+  );
+  let ruleNoticeMarkEndLine = contents.findIndex(
+    line => line === RULE_NOTICE_MARK_END,
+  );
+
+  // Add rule notice markers if they don't exist
+  if (ruleNoticeMarkStartLine === -1) {
+    contents.splice(2, 0, RULE_NOTICE_MARK_START, RULE_NOTICE_MARK_END);
+    ruleNoticeMarkStartLine = 2;
+    ruleNoticeMarkEndLine = 3;
+  }
+
+  // Insert rule notices between markers.
+  contents.splice(
+    ruleNoticeMarkStartLine + 1,
+    ruleNoticeMarkEndLine - ruleNoticeMarkStartLine - 1,
+    ...getRuleNoticeLines(ruleName),
+  );
+};
+
 // copied from https://github.com/babel/babel/blob/d8da63c929f2d28c401571e2a43166678c555bc4/packages/babel-helpers/src/helpers.js#L602-L606
 /* istanbul ignore next */
 const interopRequireDefault = (obj: any): { default: any } =>
@@ -101,12 +135,11 @@ const importDefault = (moduleName: string) =>
 const requireJestRule = (name: string): RuleModule =>
   importDefault(path.join(pathTo.rules, name)) as RuleModule;
 
-const details: RuleDetails[] = Object.keys(config.configs.all.rules)
-  .map(name => name.split('/')[1])
+const details: RuleDetails[] = Object.keys(plugin.rules)
   .map(name => [name, requireJestRule(name)] as const)
   .filter(
     (nameAndRule): nameAndRule is [string, Required<RuleModule>] =>
-      !!nameAndRule[1].meta && !nameAndRule[1].meta.deprecated,
+      !!nameAndRule[1].meta,
   )
   .map(
     ([name, rule]): RuleDetails => ({
@@ -118,6 +151,7 @@ const details: RuleDetails[] = Object.keys(config.configs.all.rules)
         ? 'suggest'
         : false,
       requiresTypeChecking: rule.meta.docs.requiresTypeChecking ?? false,
+      deprecated: rule.meta.deprecated ?? false,
     }),
   );
 
@@ -126,8 +160,11 @@ details.forEach(({ name, description }) => {
 
   const contents = fs.readFileSync(pathToDoc).toString().split('\n');
 
+  // Replace the title.
   contents[0] = `# ${description} (\`${name}\`)`;
 
+  updateRuleNotices(contents, name);
+
   fs.writeFileSync(pathToDoc, format(contents.join('\n')));
 });
 
diff --git a/tools/rule-notices.ts b/tools/rule-notices.ts
new file mode 100644
index 000000000..dffc144cb
--- /dev/null
+++ b/tools/rule-notices.ts
@@ -0,0 +1,115 @@
+import plugin from '../src';
+
+// Markers so that notices and be automatically generated and written to rule doc.
+export const RULE_NOTICE_MARK_START =
+  '<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->';
+export const RULE_NOTICE_MARK_END = '<!-- /RULE_NOTICE -->';
+
+enum MESSAGE_TYPE {
+  CONFIGS = 1,
+  DEPRECATED = 2,
+  FIXABLE = 3,
+  HAS_SUGGESTIONS = 4,
+}
+
+export const MESSAGES = {
+  [MESSAGE_TYPE.CONFIGS]:
+    '💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):',
+  [MESSAGE_TYPE.DEPRECATED]: '❌ This rule is deprecated.',
+  [MESSAGE_TYPE.FIXABLE]:
+    '🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.',
+  [MESSAGE_TYPE.HAS_SUGGESTIONS]:
+    '💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).',
+};
+
+const PRETTIER_MAX_LINE_LENGTH = 80;
+
+type RuleName = keyof typeof plugin.rules;
+type Rule = typeof plugin.rules[RuleName];
+
+function getConfigsForRule(ruleName: RuleName) {
+  const { configs } = plugin;
+  const configNames: Array<keyof typeof configs> = [];
+  let configName: keyof typeof configs;
+
+  for (configName in configs) {
+    const config = configs[configName];
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- we don't have a static type for rule names
+    // @ts-ignore
+    const value = config.rules[`jest/${ruleName}`];
+    const isEnabled = [2, 'error'].includes(value);
+
+    if (isEnabled) {
+      configNames.push(configName);
+    }
+  }
+
+  return configNames.sort();
+}
+
+function configNamesToList(configNames: string[]) {
+  return `\`${configNames.join('`, `')}\``;
+}
+
+/**
+ * Determine which notices should and should not be included at the top of a rule doc.
+ */
+export function getNoticesForRule(rule: Rule) {
+  const expectedNotices: MESSAGE_TYPE[] = [];
+  const unexpectedNotices: MESSAGE_TYPE[] = [];
+
+  if (rule.meta.deprecated) {
+    expectedNotices.push(MESSAGE_TYPE.DEPRECATED);
+    unexpectedNotices.push(MESSAGE_TYPE.CONFIGS);
+  } else {
+    unexpectedNotices.push(MESSAGE_TYPE.DEPRECATED);
+    expectedNotices.push(MESSAGE_TYPE.CONFIGS);
+  }
+  if (rule.meta.fixable) {
+    expectedNotices.push(MESSAGE_TYPE.FIXABLE);
+  } else {
+    unexpectedNotices.push(MESSAGE_TYPE.FIXABLE);
+  }
+  if (rule.meta.hasSuggestions) {
+    expectedNotices.push(MESSAGE_TYPE.HAS_SUGGESTIONS);
+  } else {
+    unexpectedNotices.push(MESSAGE_TYPE.HAS_SUGGESTIONS);
+  }
+
+  return {
+    expectedNotices,
+    unexpectedNotices,
+  };
+}
+
+/**
+ * Get the lines for the notice section at the top of a rule doc.
+ */
+export function getRuleNoticeLines(ruleName: RuleName) {
+  const lines: string[] = [];
+
+  const { expectedNotices } = getNoticesForRule(plugin.rules[ruleName]);
+
+  expectedNotices.forEach(expectedNotice => {
+    lines.push(''); // Blank line first.
+
+    if (expectedNotice === MESSAGE_TYPE.CONFIGS) {
+      // This notice should have a list of the rule's configs.
+      const configsEnabled = getConfigsForRule(ruleName);
+      const message = `${MESSAGES[MESSAGE_TYPE.CONFIGS]} ${configNamesToList(
+        configsEnabled,
+      )}.`;
+
+      lines.push(message);
+    } else {
+      lines.push(MESSAGES[expectedNotice]);
+    }
+
+    if (lines[lines.length - 1].length > PRETTIER_MAX_LINE_LENGTH) {
+      // Insert Prettier ignore comment so that the notice doesn't get split onto multiple lines.
+      lines.splice(lines.length - 1, 0, '<!-- prettier-ignore -->');
+    }
+  });
+
+  return lines;
+}

From df8ed6e6c562d3ec2de3200312c543248a93d118 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Sat, 3 Sep 2022 00:03:44 -0400
Subject: [PATCH 03/23] docs: switch to Rule details

---
 docs/rules/consistent-test-it.md            | 2 +-
 docs/rules/expect-expect.md                 | 2 +-
 docs/rules/max-expects.md                   | 2 +-
 docs/rules/max-nested-describe.md           | 2 +-
 docs/rules/no-alias-methods.md              | 2 +-
 docs/rules/no-commented-out-tests.md        | 2 +-
 docs/rules/no-conditional-expect.md         | 2 +-
 docs/rules/no-conditional-in-test.md        | 2 +-
 docs/rules/no-deprecated-functions.md       | 2 +-
 docs/rules/no-disabled-tests.md             | 2 +-
 docs/rules/no-done-callback.md              | 2 +-
 docs/rules/no-duplicate-hooks.md            | 2 +-
 docs/rules/no-export.md                     | 2 +-
 docs/rules/no-focused-tests.md              | 2 +-
 docs/rules/no-hooks.md                      | 2 +-
 docs/rules/no-identical-title.md            | 2 +-
 docs/rules/no-if.md                         | 2 +-
 docs/rules/no-interpolation-in-snapshots.md | 2 +-
 docs/rules/no-jasmine-globals.md            | 2 +-
 docs/rules/no-large-snapshots.md            | 2 +-
 docs/rules/no-mocks-import.md               | 2 +-
 docs/rules/no-restricted-matchers.md        | 2 +-
 docs/rules/no-standalone-expect.md          | 2 +-
 docs/rules/no-test-prefixes.md              | 2 +-
 docs/rules/no-test-return-statement.md      | 2 +-
 docs/rules/prefer-called-with.md            | 2 +-
 docs/rules/prefer-comparison-matcher.md     | 2 +-
 docs/rules/prefer-each.md                   | 2 +-
 docs/rules/prefer-equality-matcher.md       | 2 +-
 docs/rules/prefer-expect-assertions.md      | 2 +-
 docs/rules/prefer-expect-resolves.md        | 2 +-
 docs/rules/prefer-hooks-in-order.md         | 2 +-
 docs/rules/prefer-hooks-on-top.md           | 2 +-
 docs/rules/prefer-lowercase-title.md        | 2 +-
 docs/rules/prefer-mock-promise-shorthand.md | 2 +-
 docs/rules/prefer-snapshot-hint.md          | 2 +-
 docs/rules/prefer-spy-on.md                 | 2 +-
 docs/rules/prefer-strict-equal.md           | 2 +-
 docs/rules/prefer-to-be.md                  | 2 +-
 docs/rules/prefer-to-contain.md             | 2 +-
 docs/rules/prefer-to-have-length.md         | 2 +-
 docs/rules/prefer-todo.md                   | 2 +-
 docs/rules/require-hook.md                  | 2 +-
 docs/rules/require-to-throw-message.md      | 2 +-
 docs/rules/require-top-level-describe.md    | 2 +-
 docs/rules/unbound-method.md                | 2 +-
 docs/rules/valid-describe-callback.md       | 2 +-
 docs/rules/valid-expect-in-promise.md       | 2 +-
 docs/rules/valid-expect.md                  | 2 +-
 docs/rules/valid-title.md                   | 2 +-
 src/__tests__/rules.test.ts                 | 4 ++--
 51 files changed, 52 insertions(+), 52 deletions(-)

diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md
index 713da2fb9..c7e7209d6 100644
--- a/docs/rules/consistent-test-it.md
+++ b/docs/rules/consistent-test-it.md
@@ -16,7 +16,7 @@ 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
+## Rule details
 
 This rule gives you control over the usage of these keywords in your codebase.
 
diff --git a/docs/rules/expect-expect.md b/docs/rules/expect-expect.md
index 22347da47..7f2532b76 100644
--- a/docs/rules/expect-expect.md
+++ b/docs/rules/expect-expect.md
@@ -9,7 +9,7 @@
 
 Ensure that there is at least one `expect` call made in a test.
 
-## Rule Details
+## Rule details
 
 This rule triggers when there is no call made to `expect` in a test, to prevent
 users from forgetting to add assertions.
diff --git a/docs/rules/max-expects.md b/docs/rules/max-expects.md
index fe9175101..aac03c3d3 100644
--- a/docs/rules/max-expects.md
+++ b/docs/rules/max-expects.md
@@ -11,7 +11,7 @@ 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.
 
diff --git a/docs/rules/max-nested-describe.md b/docs/rules/max-nested-describe.md
index dbff28fd5..ff0e8626b 100644
--- a/docs/rules/max-nested-describe.md
+++ b/docs/rules/max-nested-describe.md
@@ -11,7 +11,7 @@ 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.
diff --git a/docs/rules/no-alias-methods.md b/docs/rules/no-alias-methods.md
index 541041d10..af20d0992 100644
--- a/docs/rules/no-alias-methods.md
+++ b/docs/rules/no-alias-methods.md
@@ -19,7 +19,7 @@ Jest documentation is used in the code. This makes it easier to search for all
 occurrences of the method within code, and it ensures consistency among the
 method names used.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if the alias name, rather than the canonical name,
 of a method is used.
diff --git a/docs/rules/no-commented-out-tests.md b/docs/rules/no-commented-out-tests.md
index ba17dc838..ca94dde68 100644
--- a/docs/rules/no-commented-out-tests.md
+++ b/docs/rules/no-commented-out-tests.md
@@ -10,7 +10,7 @@
 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(`,
diff --git a/docs/rules/no-conditional-expect.md b/docs/rules/no-conditional-expect.md
index a51212cb0..5c69354c8 100644
--- a/docs/rules/no-conditional-expect.md
+++ b/docs/rules/no-conditional-expect.md
@@ -13,7 +13,7 @@ This rule prevents the use of `expect` in conditional blocks, such as `if`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
diff --git a/docs/rules/no-conditional-in-test.md b/docs/rules/no-conditional-in-test.md
index 06e6bf12c..8e5db2d7f 100644
--- a/docs/rules/no-conditional-in-test.md
+++ b/docs/rules/no-conditional-in-test.md
@@ -12,7 +12,7 @@ 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.
diff --git a/docs/rules/no-deprecated-functions.md b/docs/rules/no-deprecated-functions.md
index f3258d8cc..d8d65b90b 100644
--- a/docs/rules/no-deprecated-functions.md
+++ b/docs/rules/no-deprecated-functions.md
@@ -21,7 +21,7 @@ This rule requires knowing which version of Jest you're using - see
 on how that is obtained automatically and how you can explicitly provide a
 version if needed.
 
-## Rule Details
+## Rule details
 
 This rule warns about calls to deprecated functions, and provides details on
 what to replace them with, based on the version of Jest that is installed.
diff --git a/docs/rules/no-disabled-tests.md b/docs/rules/no-disabled-tests.md
index 8e2706a65..c31b854fc 100644
--- a/docs/rules/no-disabled-tests.md
+++ b/docs/rules/no-disabled-tests.md
@@ -14,7 +14,7 @@ running.
 
 This rule raises a warning about disabled tests.
 
-## Rule Details
+## Rule details
 
 There are a number of ways to disable tests in Jest:
 
diff --git a/docs/rules/no-done-callback.md b/docs/rules/no-done-callback.md
index e063e1a0c..f5f50aab8 100644
--- a/docs/rules/no-done-callback.md
+++ b/docs/rules/no-done-callback.md
@@ -59,7 +59,7 @@ test('the data is peanut butter', async () => {
 });
 ```
 
-## Rule Details
+## Rule details
 
 This rule checks the function parameter of hooks & tests for use of the `done`
 argument, suggesting you return a promise instead.
diff --git a/docs/rules/no-duplicate-hooks.md b/docs/rules/no-duplicate-hooks.md
index 6130cd5a9..3437a9aae 100644
--- a/docs/rules/no-duplicate-hooks.md
+++ b/docs/rules/no-duplicate-hooks.md
@@ -9,7 +9,7 @@
 
 A `describe` block should not contain duplicate hooks.
 
-## Rule Details
+## Rule details
 
 Examples of **incorrect** code for this rule
 
diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md
index 8200764d8..c9464f773 100644
--- a/docs/rules/no-export.md
+++ b/docs/rules/no-export.md
@@ -9,7 +9,7 @@
 
 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
diff --git a/docs/rules/no-focused-tests.md b/docs/rules/no-focused-tests.md
index 4131ed93e..343c98a83 100644
--- a/docs/rules/no-focused-tests.md
+++ b/docs/rules/no-focused-tests.md
@@ -20,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
diff --git a/docs/rules/no-hooks.md b/docs/rules/no-hooks.md
index cd953f10a..97280195b 100644
--- a/docs/rules/no-hooks.md
+++ b/docs/rules/no-hooks.md
@@ -11,7 +11,7 @@ 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:
 
diff --git a/docs/rules/no-identical-title.md b/docs/rules/no-identical-title.md
index c62e589fc..2feb5eed2 100644
--- a/docs/rules/no-identical-title.md
+++ b/docs/rules/no-identical-title.md
@@ -12,7 +12,7 @@ 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
diff --git a/docs/rules/no-if.md b/docs/rules/no-if.md
index 0e3c61fba..1ebe7b49b 100644
--- a/docs/rules/no-if.md
+++ b/docs/rules/no-if.md
@@ -17,7 +17,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.
diff --git a/docs/rules/no-interpolation-in-snapshots.md b/docs/rules/no-interpolation-in-snapshots.md
index 0539a42ff..eadd5f8e8 100644
--- a/docs/rules/no-interpolation-in-snapshots.md
+++ b/docs/rules/no-interpolation-in-snapshots.md
@@ -9,7 +9,7 @@
 
 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
diff --git a/docs/rules/no-jasmine-globals.md b/docs/rules/no-jasmine-globals.md
index 950b66e32..838072f14 100644
--- a/docs/rules/no-jasmine-globals.md
+++ b/docs/rules/no-jasmine-globals.md
@@ -17,7 +17,7 @@ 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.
diff --git a/docs/rules/no-large-snapshots.md b/docs/rules/no-large-snapshots.md
index 2b0c2c7f8..686b58fd2 100644
--- a/docs/rules/no-large-snapshots.md
+++ b/docs/rules/no-large-snapshots.md
@@ -29,7 +29,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
diff --git a/docs/rules/no-mocks-import.md b/docs/rules/no-mocks-import.md
index 54be7133b..8da9831ce 100644
--- a/docs/rules/no-mocks-import.md
+++ b/docs/rules/no-mocks-import.md
@@ -21,7 +21,7 @@ test('x', () => {
 });
 ```
 
-## Rule Details
+## Rule details
 
 This rule reports imports from a path containing a `__mocks__` component.
 
diff --git a/docs/rules/no-restricted-matchers.md b/docs/rules/no-restricted-matchers.md
index 03573ad4e..b511526fa 100644
--- a/docs/rules/no-restricted-matchers.md
+++ b/docs/rules/no-restricted-matchers.md
@@ -9,7 +9,7 @@
 
 You may want to ban specific matchers & modifiers from being used.
 
-## Rule Details
+## Rule details
 
 This rule bans specific matchers & modifiers from being used, and can suggest
 alternatives.
diff --git a/docs/rules/no-standalone-expect.md b/docs/rules/no-standalone-expect.md
index d221d3b43..a68c30dc8 100644
--- a/docs/rules/no-standalone-expect.md
+++ b/docs/rules/no-standalone-expect.md
@@ -11,7 +11,7 @@ Prevents `expect` statements outside of a `test` or `it` block. An `expect`
 within a helper function (but outside of a `test` or `it` block) will not
 trigger this rule.
 
-## Rule Details
+## Rule details
 
 This rule aims to eliminate `expect` statements that will not be executed. An
 `expect` inside of a `describe` block but outside of a `test` or `it` block or
diff --git a/docs/rules/no-test-prefixes.md b/docs/rules/no-test-prefixes.md
index ab1581826..ad9b6a901 100644
--- a/docs/rules/no-test-prefixes.md
+++ b/docs/rules/no-test-prefixes.md
@@ -19,7 +19,7 @@ multiple permutations for each:
 
 This rule enforces usages from the **only & skip** list.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if you use one of the keywords from the **'f' &
 'x'** list to focus/skip a test.
diff --git a/docs/rules/no-test-return-statement.md b/docs/rules/no-test-return-statement.md
index b744eaed1..c9675ba2b 100644
--- a/docs/rules/no-test-return-statement.md
+++ b/docs/rules/no-test-return-statement.md
@@ -12,7 +12,7 @@ Tests in Jest should be void and not return values.
 If you are returning Promises then you should update the test to use
 `async/await`.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if you use a return statement inside a test body.
 
diff --git a/docs/rules/prefer-called-with.md b/docs/rules/prefer-called-with.md
index 1753ae27b..b21544b41 100644
--- a/docs/rules/prefer-called-with.md
+++ b/docs/rules/prefer-called-with.md
@@ -16,7 +16,7 @@ matcher. When some arguments are difficult to check, using generic match like
 This rule warns if the form without argument checking is used, except for `.not`
 enforcing a function has never been called.
 
-## Rule Details
+## Rule details
 
 The following patterns are warnings:
 
diff --git a/docs/rules/prefer-comparison-matcher.md b/docs/rules/prefer-comparison-matcher.md
index a9199eabe..05b31b47a 100644
--- a/docs/rules/prefer-comparison-matcher.md
+++ b/docs/rules/prefer-comparison-matcher.md
@@ -13,7 +13,7 @@
 Jest has a number of built-in matchers for comparing numbers, which allow for
 more readable tests and error messages if an expectation fails.
 
-## Rule Details
+## Rule details
 
 This rule checks for comparisons in tests that could be replaced with one of the
 following built-in comparison matchers:
diff --git a/docs/rules/prefer-each.md b/docs/rules/prefer-each.md
index fa6ab8e2f..7017e5206 100644
--- a/docs/rules/prefer-each.md
+++ b/docs/rules/prefer-each.md
@@ -9,7 +9,7 @@
 
 Reports where you might be able to use `.each` instead of native loops.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if you use test case functions like `describe`,
 `test`, and `it`, in a native loop - generally you should be able to use `.each`
diff --git a/docs/rules/prefer-equality-matcher.md b/docs/rules/prefer-equality-matcher.md
index c2d0f1ace..c4ad5f431 100644
--- a/docs/rules/prefer-equality-matcher.md
+++ b/docs/rules/prefer-equality-matcher.md
@@ -13,7 +13,7 @@
 Jest has built-in matchers for expecting equality, which allow for more readable
 tests and error messages if an expectation fails.
 
-## Rule Details
+## Rule details
 
 This rule checks for _strict_ equality checks (`===` & `!==`) in tests that
 could be replaced with one of the following built-in equality matchers:
diff --git a/docs/rules/prefer-expect-assertions.md b/docs/rules/prefer-expect-assertions.md
index 2b2194947..22a7d54eb 100644
--- a/docs/rules/prefer-expect-assertions.md
+++ b/docs/rules/prefer-expect-assertions.md
@@ -13,7 +13,7 @@
 Ensure every test to have either `expect.assertions(<number of assertions>)` OR
 `expect.hasAssertions()` as its first expression.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if,
 
diff --git a/docs/rules/prefer-expect-resolves.md b/docs/rules/prefer-expect-resolves.md
index c01dc46f3..36c72bd0f 100644
--- a/docs/rules/prefer-expect-resolves.md
+++ b/docs/rules/prefer-expect-resolves.md
@@ -25,7 +25,7 @@ behaviour and output from `jest`.
 Additionally, favoring the first style ensures consistency with its `rejects`
 counterpart, as there is no way of "awaiting" a rejection.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if an `await` is done within an `expect`, and
 recommends using `resolves` instead.
diff --git a/docs/rules/prefer-hooks-in-order.md b/docs/rules/prefer-hooks-in-order.md
index 10f9d338a..c9a042fa9 100644
--- a/docs/rules/prefer-hooks-in-order.md
+++ b/docs/rules/prefer-hooks-in-order.md
@@ -18,7 +18,7 @@ specific order:
 This rule aims to make that more obvious by enforcing grouped hooks be setup in
 that order within tests.
 
-## Rule Details
+## Rule details
 
 Examples of **incorrect** code for this rule
 
diff --git a/docs/rules/prefer-hooks-on-top.md b/docs/rules/prefer-hooks-on-top.md
index aa3f636f7..6c1d058ad 100644
--- a/docs/rules/prefer-hooks-on-top.md
+++ b/docs/rules/prefer-hooks-on-top.md
@@ -13,7 +13,7 @@ cases.
 
 This rule helps to ensure that hooks are always defined before test cases.
 
-## Rule Details
+## Rule details
 
 Examples of **incorrect** code for this rule
 
diff --git a/docs/rules/prefer-lowercase-title.md b/docs/rules/prefer-lowercase-title.md
index 2f45edbcc..e2bd3bccf 100644
--- a/docs/rules/prefer-lowercase-title.md
+++ b/docs/rules/prefer-lowercase-title.md
@@ -10,7 +10,7 @@
 
 <!-- /RULE_NOTICE -->
 
-## Rule Details
+## Rule details
 
 Enforce `it`, `test` and `describe` to have descriptions that begin with a
 lowercase letter. This provides more readable test failures. This rule is not
diff --git a/docs/rules/prefer-mock-promise-shorthand.md b/docs/rules/prefer-mock-promise-shorthand.md
index 05287bdfb..082fae1ef 100644
--- a/docs/rules/prefer-mock-promise-shorthand.md
+++ b/docs/rules/prefer-mock-promise-shorthand.md
@@ -15,7 +15,7 @@ API sugar functions to reduce the amount of boilerplate you have to write.
 
 These methods should be preferred when possible.
 
-## Rule Details
+## Rule details
 
 The following patterns are warnings:
 
diff --git a/docs/rules/prefer-snapshot-hint.md b/docs/rules/prefer-snapshot-hint.md
index e5fe86f10..6d1815589 100644
--- a/docs/rules/prefer-snapshot-hint.md
+++ b/docs/rules/prefer-snapshot-hint.md
@@ -15,7 +15,7 @@ This makes it easier for reviewers to verify the snapshots during review, and
 for anyone to know whether an outdated snapshot is the correct behavior before
 updating.
 
-## Rule Details
+## Rule details
 
 This rule looks for any use of an external snapshot matcher (e.g.
 `toMatchSnapshot` and `toThrowErrorMatchingSnapshot`) and checks if they include
diff --git a/docs/rules/prefer-spy-on.md b/docs/rules/prefer-spy-on.md
index 4896e4e95..030e43298 100644
--- a/docs/rules/prefer-spy-on.md
+++ b/docs/rules/prefer-spy-on.md
@@ -29,7 +29,7 @@ jest.spyOn(Date, 'now').mockImplementation(() => 10); // Will always return 10
 jest.spyOn(Date, 'now').mockReturnValue(10); // Will always return 10
 ```
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if an object's property is overwritten with a jest
 mock.
diff --git a/docs/rules/prefer-strict-equal.md b/docs/rules/prefer-strict-equal.md
index 8ad042472..8eaf514a4 100644
--- a/docs/rules/prefer-strict-equal.md
+++ b/docs/rules/prefer-strict-equal.md
@@ -15,7 +15,7 @@ that they have the same structure. It is common to expect objects to not only
 have identical values but also to have identical keys. A stricter equality will
 catch cases where two objects do not have identical keys.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if `toEqual()` is used to assert equality.
 
diff --git a/docs/rules/prefer-to-be.md b/docs/rules/prefer-to-be.md
index 1b6043843..1fc23a04c 100644
--- a/docs/rules/prefer-to-be.md
+++ b/docs/rules/prefer-to-be.md
@@ -18,7 +18,7 @@ the most grammatically natural sentence. For `null`, `undefined`, and `NaN` this
 rule recommends using their specific `toBe` matchers, as they give better error
 messages as well.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if `toEqual()` or `toStrictEqual()` are used to
 assert a primitive literal value such as numbers, strings, and booleans.
diff --git a/docs/rules/prefer-to-contain.md b/docs/rules/prefer-to-contain.md
index 37d2465ba..cc97d67ef 100644
--- a/docs/rules/prefer-to-contain.md
+++ b/docs/rules/prefer-to-contain.md
@@ -13,7 +13,7 @@
 In order to have a better failure message, `toContain()` should be used upon
 asserting expectations on an array containing an object.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if `toBe()`, `toEqual()` or `toStrictEqual()` is
 used to assert object inclusion in an array
diff --git a/docs/rules/prefer-to-have-length.md b/docs/rules/prefer-to-have-length.md
index f480fad9f..620e3a152 100644
--- a/docs/rules/prefer-to-have-length.md
+++ b/docs/rules/prefer-to-have-length.md
@@ -13,7 +13,7 @@
 In order to have a better failure message, `toHaveLength()` should be used upon
 asserting expectations on objects length property.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if `toBe()`, `toEqual()` or `toStrictEqual()` is
 used to assert objects length property.
diff --git a/docs/rules/prefer-todo.md b/docs/rules/prefer-todo.md
index 959911572..7911006ab 100644
--- a/docs/rules/prefer-todo.md
+++ b/docs/rules/prefer-todo.md
@@ -13,7 +13,7 @@
 When test cases are empty then it is better to mark them as `test.todo` as it
 will be highlighted in the summary output.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if empty test cases are used without 'test.todo'.
 
diff --git a/docs/rules/require-hook.md b/docs/rules/require-hook.md
index e56036cb7..d49117c4d 100644
--- a/docs/rules/require-hook.md
+++ b/docs/rules/require-hook.md
@@ -19,7 +19,7 @@ executes any of the actual tests, it's important to ensure setup and teardown
 work is done inside `before*` and `after*` handlers respectively, rather than
 inside the `describe` blocks.
 
-## Rule Details
+## Rule details
 
 This rule flags any expression that is either at the toplevel of a test file or
 directly within the body of a `describe`, _except_ for the following:
diff --git a/docs/rules/require-to-throw-message.md b/docs/rules/require-to-throw-message.md
index ec1f59cd0..032b34658 100644
--- a/docs/rules/require-to-throw-message.md
+++ b/docs/rules/require-to-throw-message.md
@@ -12,7 +12,7 @@ thrown by a function call, such as in `expect(() => a()).toThrow()`. However, if
 no message is defined, then the test will pass for any thrown error. Requiring a
 message ensures that the intended error is thrown.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if `toThrow()` or `toThrowError()` is used without
 an error message.
diff --git a/docs/rules/require-top-level-describe.md b/docs/rules/require-top-level-describe.md
index c9d310c8c..4a3207f16 100644
--- a/docs/rules/require-top-level-describe.md
+++ b/docs/rules/require-top-level-describe.md
@@ -12,7 +12,7 @@ more your codebase grows, the more it becomes hard to navigate in your test
 files. This rule makes sure you provide at least a top-level `describe` block in
 your test file.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if a test case (`test` and `it`) or a hook
 (`beforeAll`, `beforeEach`, `afterEach`, `afterAll`) is not located in a
diff --git a/docs/rules/unbound-method.md b/docs/rules/unbound-method.md
index a562ff29a..b2c33d68b 100644
--- a/docs/rules/unbound-method.md
+++ b/docs/rules/unbound-method.md
@@ -7,7 +7,7 @@
 
 <!-- /RULE_NOTICE -->
 
-## Rule Details
+## Rule details
 
 This rule extends the base [`@typescript-eslint/unbound-method`][original-rule]
 rule, meaning you must depend on `@typescript-eslint/eslint-plugin` for it to
diff --git a/docs/rules/valid-describe-callback.md b/docs/rules/valid-describe-callback.md
index 1fca6fcb7..62b39e298 100644
--- a/docs/rules/valid-describe-callback.md
+++ b/docs/rules/valid-describe-callback.md
@@ -10,7 +10,7 @@
 Using an improper `describe()` callback function can lead to unexpected test
 errors.
 
-## Rule Details
+## Rule details
 
 This rule validates that the second parameter of a `describe()` function is a
 callback function. This callback function:
diff --git a/docs/rules/valid-expect-in-promise.md b/docs/rules/valid-expect-in-promise.md
index 4f4ea86e0..46bc25f4a 100644
--- a/docs/rules/valid-expect-in-promise.md
+++ b/docs/rules/valid-expect-in-promise.md
@@ -9,7 +9,7 @@
 
 Ensure promises that include expectations are returned or awaited.
 
-## Rule Details
+## Rule details
 
 This rule flags any promises within the body of a test that include expectations
 that have either not been returned or awaited.
diff --git a/docs/rules/valid-expect.md b/docs/rules/valid-expect.md
index 46bfc9e43..614c7bcfe 100644
--- a/docs/rules/valid-expect.md
+++ b/docs/rules/valid-expect.md
@@ -10,7 +10,7 @@
 Ensure `expect()` is called with a single argument and there is an actual
 expectation made.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if `expect()` is called with more than one argument
 or without arguments. It would also issue a warning if there is nothing called
diff --git a/docs/rules/valid-title.md b/docs/rules/valid-title.md
index a6027ecaf..8bd219527 100644
--- a/docs/rules/valid-title.md
+++ b/docs/rules/valid-title.md
@@ -17,7 +17,7 @@ Checks that the title of Jest blocks are valid by ensuring that titles are:
 - not prefixed with their block name,
 - have no leading or trailing spaces
 
-## Rule Details
+## Rule details
 
 **emptyTitle**
 
diff --git a/src/__tests__/rules.test.ts b/src/__tests__/rules.test.ts
index 2a39916d8..95d6b1066 100644
--- a/src/__tests__/rules.test.ts
+++ b/src/__tests__/rules.test.ts
@@ -114,8 +114,8 @@ describe('rules', () => {
         ).toStrictEqual(false);
       });
 
-      // Check for Rule Details section.
-      expect(documentContents).toContain('## Rule Details');
+      // Check for Rule details section.
+      expect(documentContents).toContain('## Rule details');
 
       // Check if the rule has configuration options.
       if (

From 707afdc61b47eb075772bd53434e56da9921d40d Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Sat, 3 Sep 2022 00:04:04 -0400
Subject: [PATCH 04/23] docs: reword suggestions

---
 docs/rules/no-done-callback.md         | 2 +-
 docs/rules/no-focused-tests.md         | 2 +-
 docs/rules/prefer-equality-matcher.md  | 2 +-
 docs/rules/prefer-expect-assertions.md | 2 +-
 docs/rules/prefer-strict-equal.md      | 2 +-
 tools/rule-notices.ts                  | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/rules/no-done-callback.md b/docs/rules/no-done-callback.md
index f5f50aab8..260ed122c 100644
--- a/docs/rules/no-done-callback.md
+++ b/docs/rules/no-done-callback.md
@@ -6,7 +6,7 @@
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
 <!-- prettier-ignore -->
-💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
 
 <!-- /RULE_NOTICE -->
 
diff --git a/docs/rules/no-focused-tests.md b/docs/rules/no-focused-tests.md
index 343c98a83..411f88132 100644
--- a/docs/rules/no-focused-tests.md
+++ b/docs/rules/no-focused-tests.md
@@ -6,7 +6,7 @@
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
 <!-- prettier-ignore -->
-💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
 
 <!-- /RULE_NOTICE -->
 
diff --git a/docs/rules/prefer-equality-matcher.md b/docs/rules/prefer-equality-matcher.md
index c4ad5f431..218e0939f 100644
--- a/docs/rules/prefer-equality-matcher.md
+++ b/docs/rules/prefer-equality-matcher.md
@@ -6,7 +6,7 @@
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
 <!-- prettier-ignore -->
-💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
 
 <!-- /RULE_NOTICE -->
 
diff --git a/docs/rules/prefer-expect-assertions.md b/docs/rules/prefer-expect-assertions.md
index 22a7d54eb..1862b9b39 100644
--- a/docs/rules/prefer-expect-assertions.md
+++ b/docs/rules/prefer-expect-assertions.md
@@ -6,7 +6,7 @@
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
 <!-- prettier-ignore -->
-💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
 
 <!-- /RULE_NOTICE -->
 
diff --git a/docs/rules/prefer-strict-equal.md b/docs/rules/prefer-strict-equal.md
index 8eaf514a4..ea5f667da 100644
--- a/docs/rules/prefer-strict-equal.md
+++ b/docs/rules/prefer-strict-equal.md
@@ -6,7 +6,7 @@
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
 <!-- prettier-ignore -->
-💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
 
 <!-- /RULE_NOTICE -->
 
diff --git a/tools/rule-notices.ts b/tools/rule-notices.ts
index dffc144cb..b1601257e 100644
--- a/tools/rule-notices.ts
+++ b/tools/rule-notices.ts
@@ -19,7 +19,7 @@ export const MESSAGES = {
   [MESSAGE_TYPE.FIXABLE]:
     '🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.',
   [MESSAGE_TYPE.HAS_SUGGESTIONS]:
-    '💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).',
+    '💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.',
 };
 
 const PRETTIER_MAX_LINE_LENGTH = 80;

From e2ef23ccd87a4f28c7e3a7dc7f4f699a62ae9d54 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Sat, 3 Sep 2022 00:06:50 -0400
Subject: [PATCH 05/23] docs: change rule notice marker

---
 docs/rules/consistent-test-it.md            | 4 ++--
 docs/rules/expect-expect.md                 | 4 ++--
 docs/rules/max-expects.md                   | 4 ++--
 docs/rules/max-nested-describe.md           | 4 ++--
 docs/rules/no-alias-methods.md              | 4 ++--
 docs/rules/no-commented-out-tests.md        | 4 ++--
 docs/rules/no-conditional-expect.md         | 4 ++--
 docs/rules/no-conditional-in-test.md        | 4 ++--
 docs/rules/no-deprecated-functions.md       | 4 ++--
 docs/rules/no-disabled-tests.md             | 4 ++--
 docs/rules/no-done-callback.md              | 4 ++--
 docs/rules/no-duplicate-hooks.md            | 4 ++--
 docs/rules/no-export.md                     | 4 ++--
 docs/rules/no-focused-tests.md              | 4 ++--
 docs/rules/no-hooks.md                      | 4 ++--
 docs/rules/no-identical-title.md            | 4 ++--
 docs/rules/no-if.md                         | 4 ++--
 docs/rules/no-interpolation-in-snapshots.md | 4 ++--
 docs/rules/no-jasmine-globals.md            | 4 ++--
 docs/rules/no-large-snapshots.md            | 4 ++--
 docs/rules/no-mocks-import.md               | 4 ++--
 docs/rules/no-restricted-matchers.md        | 4 ++--
 docs/rules/no-standalone-expect.md          | 4 ++--
 docs/rules/no-test-prefixes.md              | 4 ++--
 docs/rules/no-test-return-statement.md      | 4 ++--
 docs/rules/prefer-called-with.md            | 4 ++--
 docs/rules/prefer-comparison-matcher.md     | 4 ++--
 docs/rules/prefer-each.md                   | 4 ++--
 docs/rules/prefer-equality-matcher.md       | 4 ++--
 docs/rules/prefer-expect-assertions.md      | 4 ++--
 docs/rules/prefer-expect-resolves.md        | 4 ++--
 docs/rules/prefer-hooks-in-order.md         | 4 ++--
 docs/rules/prefer-hooks-on-top.md           | 4 ++--
 docs/rules/prefer-lowercase-title.md        | 4 ++--
 docs/rules/prefer-mock-promise-shorthand.md | 4 ++--
 docs/rules/prefer-snapshot-hint.md          | 4 ++--
 docs/rules/prefer-spy-on.md                 | 4 ++--
 docs/rules/prefer-strict-equal.md           | 4 ++--
 docs/rules/prefer-to-be.md                  | 4 ++--
 docs/rules/prefer-to-contain.md             | 4 ++--
 docs/rules/prefer-to-have-length.md         | 4 ++--
 docs/rules/prefer-todo.md                   | 4 ++--
 docs/rules/require-hook.md                  | 4 ++--
 docs/rules/require-to-throw-message.md      | 4 ++--
 docs/rules/require-top-level-describe.md    | 4 ++--
 docs/rules/unbound-method.md                | 4 ++--
 docs/rules/valid-describe-callback.md       | 4 ++--
 docs/rules/valid-expect-in-promise.md       | 4 ++--
 docs/rules/valid-expect.md                  | 4 ++--
 docs/rules/valid-title.md                   | 4 ++--
 tools/rule-notices.ts                       | 4 ++--
 51 files changed, 102 insertions(+), 102 deletions(-)

diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md
index c7e7209d6..c3c2b5b32 100644
--- a/docs/rules/consistent-test-it.md
+++ b/docs/rules/consistent-test-it.md
@@ -1,6 +1,6 @@
 # Have control over `test` and `it` usages (`consistent-test-it`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Jest allows you to choose how you want to define your tests, using the `it` or
 the `test` keywords, with multiple permutations for each:
diff --git a/docs/rules/expect-expect.md b/docs/rules/expect-expect.md
index 7f2532b76..bd310ba38 100644
--- a/docs/rules/expect-expect.md
+++ b/docs/rules/expect-expect.md
@@ -1,11 +1,11 @@
 # Enforce assertion to be made in a test body (`expect-expect`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Ensure that there is at least one `expect` call made in a test.
 
diff --git a/docs/rules/max-expects.md b/docs/rules/max-expects.md
index aac03c3d3..af4325508 100644
--- a/docs/rules/max-expects.md
+++ b/docs/rules/max-expects.md
@@ -1,11 +1,11 @@
 # Enforces a maximum number assertion calls in a test body (`max-expects`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 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
diff --git a/docs/rules/max-nested-describe.md b/docs/rules/max-nested-describe.md
index ff0e8626b..f3097508b 100644
--- a/docs/rules/max-nested-describe.md
+++ b/docs/rules/max-nested-describe.md
@@ -1,11 +1,11 @@
 # Enforces a maximum depth to nested describe calls (`max-nested-describe`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 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
diff --git a/docs/rules/no-alias-methods.md b/docs/rules/no-alias-methods.md
index af20d0992..7c745cf6d 100644
--- a/docs/rules/no-alias-methods.md
+++ b/docs/rules/no-alias-methods.md
@@ -1,6 +1,6 @@
 # Disallow alias methods (`no-alias-methods`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 > These aliases are going to be removed in the next major version of Jest - see
 > https://github.com/facebook/jest/issues/13164 for more
diff --git a/docs/rules/no-commented-out-tests.md b/docs/rules/no-commented-out-tests.md
index ca94dde68..eab7f68f1 100644
--- a/docs/rules/no-commented-out-tests.md
+++ b/docs/rules/no-commented-out-tests.md
@@ -1,11 +1,11 @@
 # Disallow commented out tests (`no-commented-out-tests`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 This rule raises a warning about commented out tests. It's similar to
 no-disabled-tests rule.
diff --git a/docs/rules/no-conditional-expect.md b/docs/rules/no-conditional-expect.md
index 5c69354c8..9589bc0e2 100644
--- a/docs/rules/no-conditional-expect.md
+++ b/docs/rules/no-conditional-expect.md
@@ -1,11 +1,11 @@
 # Prevent calling `expect` conditionally (`no-conditional-expect`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 This rule prevents the use of `expect` in conditional blocks, such as `if`s &
 `catch`s.
diff --git a/docs/rules/no-conditional-in-test.md b/docs/rules/no-conditional-in-test.md
index 8e5db2d7f..a3c408867 100644
--- a/docs/rules/no-conditional-in-test.md
+++ b/docs/rules/no-conditional-in-test.md
@@ -1,11 +1,11 @@
 # Disallow conditional logic in tests (`no-conditional-in-test`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 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
diff --git a/docs/rules/no-deprecated-functions.md b/docs/rules/no-deprecated-functions.md
index d8d65b90b..702d88620 100644
--- a/docs/rules/no-deprecated-functions.md
+++ b/docs/rules/no-deprecated-functions.md
@@ -1,6 +1,6 @@
 # Disallow use of deprecated functions (`no-deprecated-functions`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 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.
diff --git a/docs/rules/no-disabled-tests.md b/docs/rules/no-disabled-tests.md
index c31b854fc..6bdf38841 100644
--- a/docs/rules/no-disabled-tests.md
+++ b/docs/rules/no-disabled-tests.md
@@ -1,11 +1,11 @@
 # Disallow disabled tests (`no-disabled-tests`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 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
diff --git a/docs/rules/no-done-callback.md b/docs/rules/no-done-callback.md
index 260ed122c..61ab187fe 100644
--- a/docs/rules/no-done-callback.md
+++ b/docs/rules/no-done-callback.md
@@ -1,6 +1,6 @@
 # Avoid using a callback in asynchronous tests and hooks (`no-done-callback`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 When calling asynchronous code in hooks and tests, `jest` needs to know when the
 asynchronous work is complete to progress the current run.
diff --git a/docs/rules/no-duplicate-hooks.md b/docs/rules/no-duplicate-hooks.md
index 3437a9aae..2b04e4d3f 100644
--- a/docs/rules/no-duplicate-hooks.md
+++ b/docs/rules/no-duplicate-hooks.md
@@ -1,11 +1,11 @@
 # Disallow duplicate setup and teardown hooks (`no-duplicate-hooks`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 A `describe` block should not contain duplicate hooks.
 
diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md
index c9464f773..a51cabec3 100644
--- a/docs/rules/no-export.md
+++ b/docs/rules/no-export.md
@@ -1,11 +1,11 @@
 # Disallow using `exports` in files containing tests (`no-export`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Prevents using `exports` if a file has one or more tests in it.
 
diff --git a/docs/rules/no-focused-tests.md b/docs/rules/no-focused-tests.md
index 411f88132..c23bdad2b 100644
--- a/docs/rules/no-focused-tests.md
+++ b/docs/rules/no-focused-tests.md
@@ -1,6 +1,6 @@
 # Disallow focused tests (`no-focused-tests`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 <!-- prettier-ignore -->
 Jest has a feature that allows you to focus tests by appending `.only` or
diff --git a/docs/rules/no-hooks.md b/docs/rules/no-hooks.md
index 97280195b..3fe0a613d 100644
--- a/docs/rules/no-hooks.md
+++ b/docs/rules/no-hooks.md
@@ -1,11 +1,11 @@
 # Disallow setup and teardown hooks (`no-hooks`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 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
diff --git a/docs/rules/no-identical-title.md b/docs/rules/no-identical-title.md
index 2feb5eed2..c8272e2ad 100644
--- a/docs/rules/no-identical-title.md
+++ b/docs/rules/no-identical-title.md
@@ -1,11 +1,11 @@
 # Disallow identical titles (`no-identical-title`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 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
diff --git a/docs/rules/no-if.md b/docs/rules/no-if.md
index 1ebe7b49b..0579d04c7 100644
--- a/docs/rules/no-if.md
+++ b/docs/rules/no-if.md
@@ -1,10 +1,10 @@
 # Disallow conditional logic (`no-if`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 ❌ This rule is deprecated.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 This rule has been deprecated in favor of
 [`no-conditional-in-test`](no-conditional-in-test.md).
diff --git a/docs/rules/no-interpolation-in-snapshots.md b/docs/rules/no-interpolation-in-snapshots.md
index eadd5f8e8..212cbbb5e 100644
--- a/docs/rules/no-interpolation-in-snapshots.md
+++ b/docs/rules/no-interpolation-in-snapshots.md
@@ -1,11 +1,11 @@
 # Disallow string interpolation inside snapshots (`no-interpolation-in-snapshots`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Prevents the use of string interpolations in snapshots.
 
diff --git a/docs/rules/no-jasmine-globals.md b/docs/rules/no-jasmine-globals.md
index 838072f14..c0dd0533e 100644
--- a/docs/rules/no-jasmine-globals.md
+++ b/docs/rules/no-jasmine-globals.md
@@ -1,6 +1,6 @@
 # Disallow Jasmine globals (`no-jasmine-globals`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 `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
diff --git a/docs/rules/no-large-snapshots.md b/docs/rules/no-large-snapshots.md
index 686b58fd2..5e92055fb 100644
--- a/docs/rules/no-large-snapshots.md
+++ b/docs/rules/no-large-snapshots.md
@@ -1,11 +1,11 @@
 # disallow large snapshots (`no-large-snapshots`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 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
diff --git a/docs/rules/no-mocks-import.md b/docs/rules/no-mocks-import.md
index 8da9831ce..b8de330e9 100644
--- a/docs/rules/no-mocks-import.md
+++ b/docs/rules/no-mocks-import.md
@@ -1,11 +1,11 @@
 # Disallow manually importing from `__mocks__` (`no-mocks-import`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 When using `jest.mock`, your tests (just like the code being tested) should
 import from `./x`, not `./__mocks__/x`. Not following this rule can lead to
diff --git a/docs/rules/no-restricted-matchers.md b/docs/rules/no-restricted-matchers.md
index b511526fa..23709144b 100644
--- a/docs/rules/no-restricted-matchers.md
+++ b/docs/rules/no-restricted-matchers.md
@@ -1,11 +1,11 @@
 # Disallow specific matchers & modifiers (`no-restricted-matchers`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 You may want to ban specific matchers & modifiers from being used.
 
diff --git a/docs/rules/no-standalone-expect.md b/docs/rules/no-standalone-expect.md
index a68c30dc8..ce7ab4a33 100644
--- a/docs/rules/no-standalone-expect.md
+++ b/docs/rules/no-standalone-expect.md
@@ -1,11 +1,11 @@
 # Disallow using `expect` outside of `it` or `test` blocks (`no-standalone-expect`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Prevents `expect` statements outside of a `test` or `it` block. An `expect`
 within a helper function (but outside of a `test` or `it` block) will not
diff --git a/docs/rules/no-test-prefixes.md b/docs/rules/no-test-prefixes.md
index ad9b6a901..cea72b06d 100644
--- a/docs/rules/no-test-prefixes.md
+++ b/docs/rules/no-test-prefixes.md
@@ -1,6 +1,6 @@
 # Use `.only` and `.skip` over `f` and `x` (`no-test-prefixes`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Jest allows you to choose how you want to define focused and skipped tests, with
 multiple permutations for each:
diff --git a/docs/rules/no-test-return-statement.md b/docs/rules/no-test-return-statement.md
index c9675ba2b..1fdb94f47 100644
--- a/docs/rules/no-test-return-statement.md
+++ b/docs/rules/no-test-return-statement.md
@@ -1,11 +1,11 @@
 # Disallow explicitly returning from tests (`no-test-return-statement`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Tests in Jest should be void and not return values.
 
diff --git a/docs/rules/prefer-called-with.md b/docs/rules/prefer-called-with.md
index b21544b41..81473841c 100644
--- a/docs/rules/prefer-called-with.md
+++ b/docs/rules/prefer-called-with.md
@@ -1,11 +1,11 @@
 # Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` (`prefer-called-with`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 The `toBeCalled()` matcher is used to assert that a mock function has been
 called one or more times, without checking the arguments passed. The assertion
diff --git a/docs/rules/prefer-comparison-matcher.md b/docs/rules/prefer-comparison-matcher.md
index 05b31b47a..615f20063 100644
--- a/docs/rules/prefer-comparison-matcher.md
+++ b/docs/rules/prefer-comparison-matcher.md
@@ -1,6 +1,6 @@
 # Suggest using the built-in comparison matchers (`prefer-comparison-matcher`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Jest has a number of built-in matchers for comparing numbers, which allow for
 more readable tests and error messages if an expectation fails.
diff --git a/docs/rules/prefer-each.md b/docs/rules/prefer-each.md
index 7017e5206..e54adc787 100644
--- a/docs/rules/prefer-each.md
+++ b/docs/rules/prefer-each.md
@@ -1,11 +1,11 @@
 # Prefer using `.each` rather than manual loops (`prefer-each`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Reports where you might be able to use `.each` instead of native loops.
 
diff --git a/docs/rules/prefer-equality-matcher.md b/docs/rules/prefer-equality-matcher.md
index 218e0939f..634a1686a 100644
--- a/docs/rules/prefer-equality-matcher.md
+++ b/docs/rules/prefer-equality-matcher.md
@@ -1,6 +1,6 @@
 # Suggest using the built-in equality matchers (`prefer-equality-matcher`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Jest has built-in matchers for expecting equality, which allow for more readable
 tests and error messages if an expectation fails.
diff --git a/docs/rules/prefer-expect-assertions.md b/docs/rules/prefer-expect-assertions.md
index 1862b9b39..3cb0d3695 100644
--- a/docs/rules/prefer-expect-assertions.md
+++ b/docs/rules/prefer-expect-assertions.md
@@ -1,6 +1,6 @@
 # Suggest using `expect.assertions()` OR `expect.hasAssertions()` (`prefer-expect-assertions`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Ensure every test to have either `expect.assertions(<number of assertions>)` OR
 `expect.hasAssertions()` as its first expression.
diff --git a/docs/rules/prefer-expect-resolves.md b/docs/rules/prefer-expect-resolves.md
index 36c72bd0f..a67a43a5a 100644
--- a/docs/rules/prefer-expect-resolves.md
+++ b/docs/rules/prefer-expect-resolves.md
@@ -1,6 +1,6 @@
 # Prefer `await expect(...).resolves` over `expect(await ...)` syntax (`prefer-expect-resolves`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 When working with promises, there are two primary ways you can test the resolved
 value:
diff --git a/docs/rules/prefer-hooks-in-order.md b/docs/rules/prefer-hooks-in-order.md
index c9a042fa9..739614715 100644
--- a/docs/rules/prefer-hooks-in-order.md
+++ b/docs/rules/prefer-hooks-in-order.md
@@ -1,11 +1,11 @@
 # Prefer having hooks in a consistent order (`prefer-hooks-in-order`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 While hooks can be setup in any order, they're always called by `jest` in this
 specific order:
diff --git a/docs/rules/prefer-hooks-on-top.md b/docs/rules/prefer-hooks-on-top.md
index 6c1d058ad..bbc35b525 100644
--- a/docs/rules/prefer-hooks-on-top.md
+++ b/docs/rules/prefer-hooks-on-top.md
@@ -1,11 +1,11 @@
 # Suggest having hooks before any test cases (`prefer-hooks-on-top`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 While hooks can be setup anywhere in a test file, they are always called in a
 specific order, which means it can be confusing if they're intermixed with test
diff --git a/docs/rules/prefer-lowercase-title.md b/docs/rules/prefer-lowercase-title.md
index e2bd3bccf..76f753e71 100644
--- a/docs/rules/prefer-lowercase-title.md
+++ b/docs/rules/prefer-lowercase-title.md
@@ -1,6 +1,6 @@
 # Enforce lowercase test names (`prefer-lowercase-title`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 ## Rule details
 
diff --git a/docs/rules/prefer-mock-promise-shorthand.md b/docs/rules/prefer-mock-promise-shorthand.md
index 082fae1ef..f0179c551 100644
--- a/docs/rules/prefer-mock-promise-shorthand.md
+++ b/docs/rules/prefer-mock-promise-shorthand.md
@@ -1,6 +1,6 @@
 # Prefer mock resolved/rejected shorthands for promises (`prefer-mock-promise-shorthand`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 When working with mocks of functions that return promises, Jest provides some
 API sugar functions to reduce the amount of boilerplate you have to write.
diff --git a/docs/rules/prefer-snapshot-hint.md b/docs/rules/prefer-snapshot-hint.md
index 6d1815589..56f4079c5 100644
--- a/docs/rules/prefer-snapshot-hint.md
+++ b/docs/rules/prefer-snapshot-hint.md
@@ -1,11 +1,11 @@
 # Prefer including a hint with external snapshots (`prefer-snapshot-hint`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 When working with external snapshot matchers it's considered best practice to
 provide a hint (as the last argument to the matcher) describing the expected
diff --git a/docs/rules/prefer-spy-on.md b/docs/rules/prefer-spy-on.md
index 030e43298..bcfdbb9dc 100644
--- a/docs/rules/prefer-spy-on.md
+++ b/docs/rules/prefer-spy-on.md
@@ -1,6 +1,6 @@
 # Suggest using `jest.spyOn()` (`prefer-spy-on`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 When mocking a function by overwriting a property you have to manually restore
 the original implementation when cleaning up. When using `jest.spyOn()` Jest
diff --git a/docs/rules/prefer-strict-equal.md b/docs/rules/prefer-strict-equal.md
index ea5f667da..84449ceb2 100644
--- a/docs/rules/prefer-strict-equal.md
+++ b/docs/rules/prefer-strict-equal.md
@@ -1,6 +1,6 @@
 # Suggest using `toStrictEqual()` (`prefer-strict-equal`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 `toStrictEqual` not only checks that two objects contain the same data but also
 that they have the same structure. It is common to expect objects to not only
diff --git a/docs/rules/prefer-to-be.md b/docs/rules/prefer-to-be.md
index 1fc23a04c..01f46ad96 100644
--- a/docs/rules/prefer-to-be.md
+++ b/docs/rules/prefer-to-be.md
@@ -1,6 +1,6 @@
 # Suggest using `toBe()` for primitive literals (`prefer-to-be`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 When asserting against primitive literals such as numbers and strings, the
 equality matchers all operate the same, but read slightly differently in code.
diff --git a/docs/rules/prefer-to-contain.md b/docs/rules/prefer-to-contain.md
index cc97d67ef..b60c52edc 100644
--- a/docs/rules/prefer-to-contain.md
+++ b/docs/rules/prefer-to-contain.md
@@ -1,6 +1,6 @@
 # Suggest using `toContain()` (`prefer-to-contain`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 In order to have a better failure message, `toContain()` should be used upon
 asserting expectations on an array containing an object.
diff --git a/docs/rules/prefer-to-have-length.md b/docs/rules/prefer-to-have-length.md
index 620e3a152..75797c561 100644
--- a/docs/rules/prefer-to-have-length.md
+++ b/docs/rules/prefer-to-have-length.md
@@ -1,6 +1,6 @@
 # Suggest using `toHaveLength()` (`prefer-to-have-length`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 In order to have a better failure message, `toHaveLength()` should be used upon
 asserting expectations on objects length property.
diff --git a/docs/rules/prefer-todo.md b/docs/rules/prefer-todo.md
index 7911006ab..48a9280b8 100644
--- a/docs/rules/prefer-todo.md
+++ b/docs/rules/prefer-todo.md
@@ -1,6 +1,6 @@
 # Suggest using `test.todo` (`prefer-todo`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 When test cases are empty then it is better to mark them as `test.todo` as it
 will be highlighted in the summary output.
diff --git a/docs/rules/require-hook.md b/docs/rules/require-hook.md
index d49117c4d..53986c02f 100644
--- a/docs/rules/require-hook.md
+++ b/docs/rules/require-hook.md
@@ -1,11 +1,11 @@
 # Require setup and teardown code to be within a hook (`require-hook`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Often while writing tests you have some setup work that needs to happen before
 tests run, and you have some finishing work that needs to happen after tests
diff --git a/docs/rules/require-to-throw-message.md b/docs/rules/require-to-throw-message.md
index 032b34658..ec32e13b2 100644
--- a/docs/rules/require-to-throw-message.md
+++ b/docs/rules/require-to-throw-message.md
@@ -1,11 +1,11 @@
 # Require a message for `toThrow()` (`require-to-throw-message`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 `toThrow()` (and its alias `toThrowError()`) is used to check if an error is
 thrown by a function call, such as in `expect(() => a()).toThrow()`. However, if
diff --git a/docs/rules/require-top-level-describe.md b/docs/rules/require-top-level-describe.md
index 4a3207f16..75a0c57cd 100644
--- a/docs/rules/require-top-level-describe.md
+++ b/docs/rules/require-top-level-describe.md
@@ -1,11 +1,11 @@
 # Require test cases and hooks to be inside a `describe` block (`require-top-level-describe`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Jest allows you to organise your test files the way you want it. However, the
 more your codebase grows, the more it becomes hard to navigate in your test
diff --git a/docs/rules/unbound-method.md b/docs/rules/unbound-method.md
index b2c33d68b..ec1abee78 100644
--- a/docs/rules/unbound-method.md
+++ b/docs/rules/unbound-method.md
@@ -1,11 +1,11 @@
 # Enforce unbound methods are called with their expected scope (`unbound-method`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 ## Rule details
 
diff --git a/docs/rules/valid-describe-callback.md b/docs/rules/valid-describe-callback.md
index 62b39e298..19a36408a 100644
--- a/docs/rules/valid-describe-callback.md
+++ b/docs/rules/valid-describe-callback.md
@@ -1,11 +1,11 @@
 # Enforce valid `describe()` callback (`valid-describe-callback`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Using an improper `describe()` callback function can lead to unexpected test
 errors.
diff --git a/docs/rules/valid-expect-in-promise.md b/docs/rules/valid-expect-in-promise.md
index 46bc25f4a..f848686f4 100644
--- a/docs/rules/valid-expect-in-promise.md
+++ b/docs/rules/valid-expect-in-promise.md
@@ -1,11 +1,11 @@
 # Ensure promises that have expectations in their chain are valid (`valid-expect-in-promise`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Ensure promises that include expectations are returned or awaited.
 
diff --git a/docs/rules/valid-expect.md b/docs/rules/valid-expect.md
index 614c7bcfe..194f3e17d 100644
--- a/docs/rules/valid-expect.md
+++ b/docs/rules/valid-expect.md
@@ -1,11 +1,11 @@
 # Enforce valid `expect()` usage (`valid-expect`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Ensure `expect()` is called with a single argument and there is an actual
 expectation made.
diff --git a/docs/rules/valid-title.md b/docs/rules/valid-title.md
index 8bd219527..ec6c7882a 100644
--- a/docs/rules/valid-title.md
+++ b/docs/rules/valid-title.md
@@ -1,6 +1,6 @@
 # Enforce valid titles (`valid-title`)
 
-<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->
+<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
@@ -8,7 +8,7 @@
 <!-- prettier-ignore -->
 🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-<!-- /RULE_NOTICE -->
+<!-- end rules notice -->
 
 Checks that the title of Jest blocks are valid by ensuring that titles are:
 
diff --git a/tools/rule-notices.ts b/tools/rule-notices.ts
index b1601257e..620028d44 100644
--- a/tools/rule-notices.ts
+++ b/tools/rule-notices.ts
@@ -2,8 +2,8 @@ import plugin from '../src';
 
 // Markers so that notices and be automatically generated and written to rule doc.
 export const RULE_NOTICE_MARK_START =
-  '<!-- RULE_NOTICE -- Generated by `yarn tools:regenerate-docs` -->';
-export const RULE_NOTICE_MARK_END = '<!-- /RULE_NOTICE -->';
+  '<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->';
+export const RULE_NOTICE_MARK_END = '<!-- end rules notice -->';
 
 enum MESSAGE_TYPE {
   CONFIGS = 1,

From 302cc3bdce9602d5ad9a235e6aae4dd7f22aa44d Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Sat, 3 Sep 2022 00:31:40 -0400
Subject: [PATCH 06/23] test: not.toContain

---
 src/__tests__/rules.test.ts | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/src/__tests__/rules.test.ts b/src/__tests__/rules.test.ts
index 95d6b1066..533cbf3c5 100644
--- a/src/__tests__/rules.test.ts
+++ b/src/__tests__/rules.test.ts
@@ -108,11 +108,9 @@ describe('rules', () => {
       // Ensure that unexpected notices are not present.
       const { unexpectedNotices } = getNoticesForRule(rule);
 
-      unexpectedNotices.forEach(unexpectedNotice => {
-        expect(
-          documentContents.includes(MESSAGES[unexpectedNotice]),
-        ).toStrictEqual(false);
-      });
+      unexpectedNotices.forEach(unexpectedNotice =>
+        expect(documentContents).not.toContain(MESSAGES[unexpectedNotice]),
+      );
 
       // Check for Rule details section.
       expect(documentContents).toContain('## Rule details');
@@ -127,8 +125,8 @@ describe('rules', () => {
         expect(documentContents).toContain('## Options');
       } else {
         // Should NOT have any options section header:
-        expect(documentContents.includes('## Options')).toStrictEqual(false);
-        expect(documentContents.includes('## Config')).toStrictEqual(false);
+        expect(documentContents).not.toContain('## Options');
+        expect(documentContents).not.toContain('## Config');
       }
     });
   });

From 50765e65266f7016551245fb38ed553531eb70ff Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Mon, 5 Sep 2022 13:32:41 -0400
Subject: [PATCH 07/23] docs: ending marker only, no prettier disable, refactor
 rule doc header function

---
 docs/rules/consistent-test-it.md            | 14 +++---
 docs/rules/expect-expect.md                 |  9 ++--
 docs/rules/max-expects.md                   |  9 ++--
 docs/rules/max-nested-describe.md           |  9 ++--
 docs/rules/no-alias-methods.md              | 14 +++---
 docs/rules/no-commented-out-tests.md        |  9 ++--
 docs/rules/no-conditional-expect.md         |  9 ++--
 docs/rules/no-conditional-in-test.md        |  9 ++--
 docs/rules/no-deprecated-functions.md       | 14 +++---
 docs/rules/no-disabled-tests.md             |  9 ++--
 docs/rules/no-done-callback.md              | 14 +++---
 docs/rules/no-duplicate-hooks.md            |  9 ++--
 docs/rules/no-export.md                     |  9 ++--
 docs/rules/no-focused-tests.md              | 14 +++---
 docs/rules/no-hooks.md                      |  9 ++--
 docs/rules/no-identical-title.md            |  9 ++--
 docs/rules/no-if.md                         |  4 +-
 docs/rules/no-interpolation-in-snapshots.md |  9 ++--
 docs/rules/no-jasmine-globals.md            | 14 +++---
 docs/rules/no-large-snapshots.md            |  9 ++--
 docs/rules/no-mocks-import.md               |  9 ++--
 docs/rules/no-restricted-matchers.md        |  9 ++--
 docs/rules/no-standalone-expect.md          |  9 ++--
 docs/rules/no-test-prefixes.md              | 14 +++---
 docs/rules/no-test-return-statement.md      |  9 ++--
 docs/rules/prefer-called-with.md            |  9 ++--
 docs/rules/prefer-comparison-matcher.md     | 14 +++---
 docs/rules/prefer-each.md                   |  9 ++--
 docs/rules/prefer-equality-matcher.md       | 14 +++---
 docs/rules/prefer-expect-assertions.md      | 14 +++---
 docs/rules/prefer-expect-resolves.md        | 14 +++---
 docs/rules/prefer-hooks-in-order.md         |  9 ++--
 docs/rules/prefer-hooks-on-top.md           |  9 ++--
 docs/rules/prefer-lowercase-title.md        | 14 +++---
 docs/rules/prefer-mock-promise-shorthand.md | 14 +++---
 docs/rules/prefer-snapshot-hint.md          |  9 ++--
 docs/rules/prefer-spy-on.md                 | 14 +++---
 docs/rules/prefer-strict-equal.md           | 14 +++---
 docs/rules/prefer-to-be.md                  | 14 +++---
 docs/rules/prefer-to-contain.md             | 14 +++---
 docs/rules/prefer-to-have-length.md         | 14 +++---
 docs/rules/prefer-todo.md                   | 14 +++---
 docs/rules/require-hook.md                  |  9 ++--
 docs/rules/require-to-throw-message.md      |  9 ++--
 docs/rules/require-top-level-describe.md    |  9 ++--
 docs/rules/unbound-method.md                |  9 ++--
 docs/rules/valid-describe-callback.md       |  9 ++--
 docs/rules/valid-expect-in-promise.md       |  9 ++--
 docs/rules/valid-expect.md                  |  9 ++--
 docs/rules/valid-title.md                   | 14 +++---
 src/__tests__/rules.test.ts                 | 27 ++---------
 tools/regenerate-docs.ts                    | 53 +++++++++------------
 tools/rule-notices.ts                       | 12 -----
 53 files changed, 283 insertions(+), 354 deletions(-)

diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md
index c3c2b5b32..93232e773 100644
--- a/docs/rules/consistent-test-it.md
+++ b/docs/rules/consistent-test-it.md
@@ -1,14 +1,14 @@
 # Have control over `test` and `it` usages (`consistent-test-it`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Jest allows you to choose how you want to define your tests, using the `it` or
 the `test` keywords, with multiple permutations for each:
diff --git a/docs/rules/expect-expect.md b/docs/rules/expect-expect.md
index bd310ba38..b5679dc46 100644
--- a/docs/rules/expect-expect.md
+++ b/docs/rules/expect-expect.md
@@ -1,11 +1,10 @@
 # Enforce assertion to be made in a test body (`expect-expect`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Ensure that there is at least one `expect` call made in a test.
 
diff --git a/docs/rules/max-expects.md b/docs/rules/max-expects.md
index af4325508..80c2c7bb5 100644
--- a/docs/rules/max-expects.md
+++ b/docs/rules/max-expects.md
@@ -1,11 +1,10 @@
 # Enforces a maximum number assertion calls in a test body (`max-expects`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 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
diff --git a/docs/rules/max-nested-describe.md b/docs/rules/max-nested-describe.md
index f3097508b..0aff77a04 100644
--- a/docs/rules/max-nested-describe.md
+++ b/docs/rules/max-nested-describe.md
@@ -1,11 +1,10 @@
 # Enforces a maximum depth to nested describe calls (`max-nested-describe`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 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
diff --git a/docs/rules/no-alias-methods.md b/docs/rules/no-alias-methods.md
index 7c745cf6d..554e041c3 100644
--- a/docs/rules/no-alias-methods.md
+++ b/docs/rules/no-alias-methods.md
@@ -1,14 +1,14 @@
 # Disallow alias methods (`no-alias-methods`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 > These aliases are going to be removed in the next major version of Jest - see
 > https://github.com/facebook/jest/issues/13164 for more
diff --git a/docs/rules/no-commented-out-tests.md b/docs/rules/no-commented-out-tests.md
index eab7f68f1..518a6708e 100644
--- a/docs/rules/no-commented-out-tests.md
+++ b/docs/rules/no-commented-out-tests.md
@@ -1,11 +1,10 @@
 # Disallow commented out tests (`no-commented-out-tests`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 This rule raises a warning about commented out tests. It's similar to
 no-disabled-tests rule.
diff --git a/docs/rules/no-conditional-expect.md b/docs/rules/no-conditional-expect.md
index 9589bc0e2..be7861e9e 100644
--- a/docs/rules/no-conditional-expect.md
+++ b/docs/rules/no-conditional-expect.md
@@ -1,11 +1,10 @@
 # Prevent calling `expect` conditionally (`no-conditional-expect`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 This rule prevents the use of `expect` in conditional blocks, such as `if`s &
 `catch`s.
diff --git a/docs/rules/no-conditional-in-test.md b/docs/rules/no-conditional-in-test.md
index a3c408867..9903b117d 100644
--- a/docs/rules/no-conditional-in-test.md
+++ b/docs/rules/no-conditional-in-test.md
@@ -1,11 +1,10 @@
 # Disallow conditional logic in tests (`no-conditional-in-test`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 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
diff --git a/docs/rules/no-deprecated-functions.md b/docs/rules/no-deprecated-functions.md
index 702d88620..9686b2490 100644
--- a/docs/rules/no-deprecated-functions.md
+++ b/docs/rules/no-deprecated-functions.md
@@ -1,14 +1,14 @@
 # Disallow use of deprecated functions (`no-deprecated-functions`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 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.
diff --git a/docs/rules/no-disabled-tests.md b/docs/rules/no-disabled-tests.md
index 6bdf38841..4096e642e 100644
--- a/docs/rules/no-disabled-tests.md
+++ b/docs/rules/no-disabled-tests.md
@@ -1,11 +1,10 @@
 # Disallow disabled tests (`no-disabled-tests`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 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
diff --git a/docs/rules/no-done-callback.md b/docs/rules/no-done-callback.md
index 61ab187fe..0ab5b5b29 100644
--- a/docs/rules/no-done-callback.md
+++ b/docs/rules/no-done-callback.md
@@ -1,14 +1,14 @@
 # Avoid using a callback in asynchronous tests and hooks (`no-done-callback`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
+💡 This rule provides
+[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
+that can be applied manually.
 
-<!-- prettier-ignore -->
-💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 When calling asynchronous code in hooks and tests, `jest` needs to know when the
 asynchronous work is complete to progress the current run.
diff --git a/docs/rules/no-duplicate-hooks.md b/docs/rules/no-duplicate-hooks.md
index 2b04e4d3f..210286fff 100644
--- a/docs/rules/no-duplicate-hooks.md
+++ b/docs/rules/no-duplicate-hooks.md
@@ -1,11 +1,10 @@
 # Disallow duplicate setup and teardown hooks (`no-duplicate-hooks`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 A `describe` block should not contain duplicate hooks.
 
diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md
index a51cabec3..3ac6a8f10 100644
--- a/docs/rules/no-export.md
+++ b/docs/rules/no-export.md
@@ -1,11 +1,10 @@
 # Disallow using `exports` in files containing tests (`no-export`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Prevents using `exports` if a file has one or more tests in it.
 
diff --git a/docs/rules/no-focused-tests.md b/docs/rules/no-focused-tests.md
index c23bdad2b..9bedfe2e3 100644
--- a/docs/rules/no-focused-tests.md
+++ b/docs/rules/no-focused-tests.md
@@ -1,14 +1,14 @@
 # Disallow focused tests (`no-focused-tests`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
-
-<!-- prettier-ignore -->
-💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
+💡 This rule provides
+[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
+that can be applied manually.
 
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 <!-- prettier-ignore -->
 Jest has a feature that allows you to focus tests by appending `.only` or
diff --git a/docs/rules/no-hooks.md b/docs/rules/no-hooks.md
index 3fe0a613d..93a9cb147 100644
--- a/docs/rules/no-hooks.md
+++ b/docs/rules/no-hooks.md
@@ -1,11 +1,10 @@
 # Disallow setup and teardown hooks (`no-hooks`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 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
diff --git a/docs/rules/no-identical-title.md b/docs/rules/no-identical-title.md
index c8272e2ad..4fca9551f 100644
--- a/docs/rules/no-identical-title.md
+++ b/docs/rules/no-identical-title.md
@@ -1,11 +1,10 @@
 # Disallow identical titles (`no-identical-title`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 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
diff --git a/docs/rules/no-if.md b/docs/rules/no-if.md
index 0579d04c7..195559173 100644
--- a/docs/rules/no-if.md
+++ b/docs/rules/no-if.md
@@ -1,10 +1,8 @@
 # Disallow conditional logic (`no-if`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
-
 ❌ This rule is deprecated.
 
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 This rule has been deprecated in favor of
 [`no-conditional-in-test`](no-conditional-in-test.md).
diff --git a/docs/rules/no-interpolation-in-snapshots.md b/docs/rules/no-interpolation-in-snapshots.md
index 212cbbb5e..62787601c 100644
--- a/docs/rules/no-interpolation-in-snapshots.md
+++ b/docs/rules/no-interpolation-in-snapshots.md
@@ -1,11 +1,10 @@
 # Disallow string interpolation inside snapshots (`no-interpolation-in-snapshots`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Prevents the use of string interpolations in snapshots.
 
diff --git a/docs/rules/no-jasmine-globals.md b/docs/rules/no-jasmine-globals.md
index c0dd0533e..cb9b7e2ac 100644
--- a/docs/rules/no-jasmine-globals.md
+++ b/docs/rules/no-jasmine-globals.md
@@ -1,14 +1,14 @@
 # Disallow Jasmine globals (`no-jasmine-globals`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 `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
diff --git a/docs/rules/no-large-snapshots.md b/docs/rules/no-large-snapshots.md
index 5e92055fb..70bd0bdb0 100644
--- a/docs/rules/no-large-snapshots.md
+++ b/docs/rules/no-large-snapshots.md
@@ -1,11 +1,10 @@
 # disallow large snapshots (`no-large-snapshots`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 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
diff --git a/docs/rules/no-mocks-import.md b/docs/rules/no-mocks-import.md
index b8de330e9..56bf927e5 100644
--- a/docs/rules/no-mocks-import.md
+++ b/docs/rules/no-mocks-import.md
@@ -1,11 +1,10 @@
 # Disallow manually importing from `__mocks__` (`no-mocks-import`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 When using `jest.mock`, your tests (just like the code being tested) should
 import from `./x`, not `./__mocks__/x`. Not following this rule can lead to
diff --git a/docs/rules/no-restricted-matchers.md b/docs/rules/no-restricted-matchers.md
index 23709144b..3ea5042bc 100644
--- a/docs/rules/no-restricted-matchers.md
+++ b/docs/rules/no-restricted-matchers.md
@@ -1,11 +1,10 @@
 # Disallow specific matchers & modifiers (`no-restricted-matchers`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 You may want to ban specific matchers & modifiers from being used.
 
diff --git a/docs/rules/no-standalone-expect.md b/docs/rules/no-standalone-expect.md
index ce7ab4a33..f2a9b5844 100644
--- a/docs/rules/no-standalone-expect.md
+++ b/docs/rules/no-standalone-expect.md
@@ -1,11 +1,10 @@
 # Disallow using `expect` outside of `it` or `test` blocks (`no-standalone-expect`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Prevents `expect` statements outside of a `test` or `it` block. An `expect`
 within a helper function (but outside of a `test` or `it` block) will not
diff --git a/docs/rules/no-test-prefixes.md b/docs/rules/no-test-prefixes.md
index cea72b06d..29fe3d639 100644
--- a/docs/rules/no-test-prefixes.md
+++ b/docs/rules/no-test-prefixes.md
@@ -1,14 +1,14 @@
 # Use `.only` and `.skip` over `f` and `x` (`no-test-prefixes`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Jest allows you to choose how you want to define focused and skipped tests, with
 multiple permutations for each:
diff --git a/docs/rules/no-test-return-statement.md b/docs/rules/no-test-return-statement.md
index 1fdb94f47..b21ac8102 100644
--- a/docs/rules/no-test-return-statement.md
+++ b/docs/rules/no-test-return-statement.md
@@ -1,11 +1,10 @@
 # Disallow explicitly returning from tests (`no-test-return-statement`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Tests in Jest should be void and not return values.
 
diff --git a/docs/rules/prefer-called-with.md b/docs/rules/prefer-called-with.md
index 81473841c..5e599cc47 100644
--- a/docs/rules/prefer-called-with.md
+++ b/docs/rules/prefer-called-with.md
@@ -1,11 +1,10 @@
 # Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` (`prefer-called-with`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 The `toBeCalled()` matcher is used to assert that a mock function has been
 called one or more times, without checking the arguments passed. The assertion
diff --git a/docs/rules/prefer-comparison-matcher.md b/docs/rules/prefer-comparison-matcher.md
index 615f20063..9d83630f6 100644
--- a/docs/rules/prefer-comparison-matcher.md
+++ b/docs/rules/prefer-comparison-matcher.md
@@ -1,14 +1,14 @@
 # Suggest using the built-in comparison matchers (`prefer-comparison-matcher`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Jest has a number of built-in matchers for comparing numbers, which allow for
 more readable tests and error messages if an expectation fails.
diff --git a/docs/rules/prefer-each.md b/docs/rules/prefer-each.md
index e54adc787..3a5591bdf 100644
--- a/docs/rules/prefer-each.md
+++ b/docs/rules/prefer-each.md
@@ -1,11 +1,10 @@
 # Prefer using `.each` rather than manual loops (`prefer-each`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Reports where you might be able to use `.each` instead of native loops.
 
diff --git a/docs/rules/prefer-equality-matcher.md b/docs/rules/prefer-equality-matcher.md
index 634a1686a..e51e10049 100644
--- a/docs/rules/prefer-equality-matcher.md
+++ b/docs/rules/prefer-equality-matcher.md
@@ -1,14 +1,14 @@
 # Suggest using the built-in equality matchers (`prefer-equality-matcher`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+💡 This rule provides
+[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
+that can be applied manually.
 
-<!-- prettier-ignore -->
-💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Jest has built-in matchers for expecting equality, which allow for more readable
 tests and error messages if an expectation fails.
diff --git a/docs/rules/prefer-expect-assertions.md b/docs/rules/prefer-expect-assertions.md
index 3cb0d3695..9265fd2a0 100644
--- a/docs/rules/prefer-expect-assertions.md
+++ b/docs/rules/prefer-expect-assertions.md
@@ -1,14 +1,14 @@
 # Suggest using `expect.assertions()` OR `expect.hasAssertions()` (`prefer-expect-assertions`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+💡 This rule provides
+[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
+that can be applied manually.
 
-<!-- prettier-ignore -->
-💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Ensure every test to have either `expect.assertions(<number of assertions>)` OR
 `expect.hasAssertions()` as its first expression.
diff --git a/docs/rules/prefer-expect-resolves.md b/docs/rules/prefer-expect-resolves.md
index a67a43a5a..65d352bc7 100644
--- a/docs/rules/prefer-expect-resolves.md
+++ b/docs/rules/prefer-expect-resolves.md
@@ -1,14 +1,14 @@
 # Prefer `await expect(...).resolves` over `expect(await ...)` syntax (`prefer-expect-resolves`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 When working with promises, there are two primary ways you can test the resolved
 value:
diff --git a/docs/rules/prefer-hooks-in-order.md b/docs/rules/prefer-hooks-in-order.md
index 739614715..ded06b160 100644
--- a/docs/rules/prefer-hooks-in-order.md
+++ b/docs/rules/prefer-hooks-in-order.md
@@ -1,11 +1,10 @@
 # Prefer having hooks in a consistent order (`prefer-hooks-in-order`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 While hooks can be setup in any order, they're always called by `jest` in this
 specific order:
diff --git a/docs/rules/prefer-hooks-on-top.md b/docs/rules/prefer-hooks-on-top.md
index bbc35b525..499679b9d 100644
--- a/docs/rules/prefer-hooks-on-top.md
+++ b/docs/rules/prefer-hooks-on-top.md
@@ -1,11 +1,10 @@
 # Suggest having hooks before any test cases (`prefer-hooks-on-top`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 While hooks can be setup anywhere in a test file, they are always called in a
 specific order, which means it can be confusing if they're intermixed with test
diff --git a/docs/rules/prefer-lowercase-title.md b/docs/rules/prefer-lowercase-title.md
index 76f753e71..87149cfe8 100644
--- a/docs/rules/prefer-lowercase-title.md
+++ b/docs/rules/prefer-lowercase-title.md
@@ -1,14 +1,14 @@
 # Enforce lowercase test names (`prefer-lowercase-title`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 ## Rule details
 
diff --git a/docs/rules/prefer-mock-promise-shorthand.md b/docs/rules/prefer-mock-promise-shorthand.md
index f0179c551..6e8ae0829 100644
--- a/docs/rules/prefer-mock-promise-shorthand.md
+++ b/docs/rules/prefer-mock-promise-shorthand.md
@@ -1,14 +1,14 @@
 # Prefer mock resolved/rejected shorthands for promises (`prefer-mock-promise-shorthand`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 When working with mocks of functions that return promises, Jest provides some
 API sugar functions to reduce the amount of boilerplate you have to write.
diff --git a/docs/rules/prefer-snapshot-hint.md b/docs/rules/prefer-snapshot-hint.md
index 56f4079c5..621707bf7 100644
--- a/docs/rules/prefer-snapshot-hint.md
+++ b/docs/rules/prefer-snapshot-hint.md
@@ -1,11 +1,10 @@
 # Prefer including a hint with external snapshots (`prefer-snapshot-hint`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 When working with external snapshot matchers it's considered best practice to
 provide a hint (as the last argument to the matcher) describing the expected
diff --git a/docs/rules/prefer-spy-on.md b/docs/rules/prefer-spy-on.md
index bcfdbb9dc..ede3d1712 100644
--- a/docs/rules/prefer-spy-on.md
+++ b/docs/rules/prefer-spy-on.md
@@ -1,14 +1,14 @@
 # Suggest using `jest.spyOn()` (`prefer-spy-on`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 When mocking a function by overwriting a property you have to manually restore
 the original implementation when cleaning up. When using `jest.spyOn()` Jest
diff --git a/docs/rules/prefer-strict-equal.md b/docs/rules/prefer-strict-equal.md
index 84449ceb2..e86628950 100644
--- a/docs/rules/prefer-strict-equal.md
+++ b/docs/rules/prefer-strict-equal.md
@@ -1,14 +1,14 @@
 # Suggest using `toStrictEqual()` (`prefer-strict-equal`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
+💡 This rule provides
+[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
+that can be applied manually.
 
-<!-- prettier-ignore -->
-💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 `toStrictEqual` not only checks that two objects contain the same data but also
 that they have the same structure. It is common to expect objects to not only
diff --git a/docs/rules/prefer-to-be.md b/docs/rules/prefer-to-be.md
index 01f46ad96..0d30a7f94 100644
--- a/docs/rules/prefer-to-be.md
+++ b/docs/rules/prefer-to-be.md
@@ -1,14 +1,14 @@
 # Suggest using `toBe()` for primitive literals (`prefer-to-be`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `style`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`.
+🔧 This rule is automatically fixable using the `--fix`
+[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
+on the command line.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 When asserting against primitive literals such as numbers and strings, the
 equality matchers all operate the same, but read slightly differently in code.
diff --git a/docs/rules/prefer-to-contain.md b/docs/rules/prefer-to-contain.md
index b60c52edc..e4da2110d 100644
--- a/docs/rules/prefer-to-contain.md
+++ b/docs/rules/prefer-to-contain.md
@@ -1,14 +1,14 @@
 # Suggest using `toContain()` (`prefer-to-contain`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `style`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`.
+🔧 This rule is automatically fixable using the `--fix`
+[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
+on the command line.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 In order to have a better failure message, `toContain()` should be used upon
 asserting expectations on an array containing an object.
diff --git a/docs/rules/prefer-to-have-length.md b/docs/rules/prefer-to-have-length.md
index 75797c561..6ea672e90 100644
--- a/docs/rules/prefer-to-have-length.md
+++ b/docs/rules/prefer-to-have-length.md
@@ -1,14 +1,14 @@
 # Suggest using `toHaveLength()` (`prefer-to-have-length`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `style`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`.
+🔧 This rule is automatically fixable using the `--fix`
+[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
+on the command line.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 In order to have a better failure message, `toHaveLength()` should be used upon
 asserting expectations on objects length property.
diff --git a/docs/rules/prefer-todo.md b/docs/rules/prefer-todo.md
index 48a9280b8..1b2629912 100644
--- a/docs/rules/prefer-todo.md
+++ b/docs/rules/prefer-todo.md
@@ -1,14 +1,14 @@
 # Suggest using `test.todo` (`prefer-todo`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 When test cases are empty then it is better to mark them as `test.todo` as it
 will be highlighted in the summary output.
diff --git a/docs/rules/require-hook.md b/docs/rules/require-hook.md
index 53986c02f..c98fb8561 100644
--- a/docs/rules/require-hook.md
+++ b/docs/rules/require-hook.md
@@ -1,11 +1,10 @@
 # Require setup and teardown code to be within a hook (`require-hook`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Often while writing tests you have some setup work that needs to happen before
 tests run, and you have some finishing work that needs to happen after tests
diff --git a/docs/rules/require-to-throw-message.md b/docs/rules/require-to-throw-message.md
index ec32e13b2..77c4598a7 100644
--- a/docs/rules/require-to-throw-message.md
+++ b/docs/rules/require-to-throw-message.md
@@ -1,11 +1,10 @@
 # Require a message for `toThrow()` (`require-to-throw-message`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 `toThrow()` (and its alias `toThrowError()`) is used to check if an error is
 thrown by a function call, such as in `expect(() => a()).toThrow()`. However, if
diff --git a/docs/rules/require-top-level-describe.md b/docs/rules/require-top-level-describe.md
index 75a0c57cd..5fb54cab1 100644
--- a/docs/rules/require-top-level-describe.md
+++ b/docs/rules/require-top-level-describe.md
@@ -1,11 +1,10 @@
 # Require test cases and hooks to be inside a `describe` block (`require-top-level-describe`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Jest allows you to organise your test files the way you want it. However, the
 more your codebase grows, the more it becomes hard to navigate in your test
diff --git a/docs/rules/unbound-method.md b/docs/rules/unbound-method.md
index ec1abee78..6549a862e 100644
--- a/docs/rules/unbound-method.md
+++ b/docs/rules/unbound-method.md
@@ -1,11 +1,10 @@
 # Enforce unbound methods are called with their expected scope (`unbound-method`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 ## Rule details
 
diff --git a/docs/rules/valid-describe-callback.md b/docs/rules/valid-describe-callback.md
index 19a36408a..30d4343f4 100644
--- a/docs/rules/valid-describe-callback.md
+++ b/docs/rules/valid-describe-callback.md
@@ -1,11 +1,10 @@
 # Enforce valid `describe()` callback (`valid-describe-callback`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Using an improper `describe()` callback function can lead to unexpected test
 errors.
diff --git a/docs/rules/valid-expect-in-promise.md b/docs/rules/valid-expect-in-promise.md
index f848686f4..24469795e 100644
--- a/docs/rules/valid-expect-in-promise.md
+++ b/docs/rules/valid-expect-in-promise.md
@@ -1,11 +1,10 @@
 # Ensure promises that have expectations in their chain are valid (`valid-expect-in-promise`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Ensure promises that include expectations are returned or awaited.
 
diff --git a/docs/rules/valid-expect.md b/docs/rules/valid-expect.md
index 194f3e17d..d8fd3142c 100644
--- a/docs/rules/valid-expect.md
+++ b/docs/rules/valid-expect.md
@@ -1,11 +1,10 @@
 # Enforce valid `expect()` usage (`valid-expect`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`.
-
-<!-- end rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Ensure `expect()` is called with a single argument and there is an actual
 expectation made.
diff --git a/docs/rules/valid-title.md b/docs/rules/valid-title.md
index ec6c7882a..eb20fc2f1 100644
--- a/docs/rules/valid-title.md
+++ b/docs/rules/valid-title.md
@@ -1,14 +1,14 @@
 # Enforce valid titles (`valid-title`)
 
-<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->
+💼 This rule is enabled in the following
+[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+`all`, `recommended`.
 
-<!-- prettier-ignore -->
-💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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.
 
-<!-- prettier-ignore -->
-🔧 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 rules notice -->
+<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
 
 Checks that the title of Jest blocks are valid by ensuring that titles are:
 
diff --git a/src/__tests__/rules.test.ts b/src/__tests__/rules.test.ts
index 533cbf3c5..7ce522205 100644
--- a/src/__tests__/rules.test.ts
+++ b/src/__tests__/rules.test.ts
@@ -1,12 +1,7 @@
 import { existsSync, readFileSync } from 'fs';
-import { EOL } from 'os';
 import { join, resolve } from 'path';
 import plugin from '../';
-import {
-  MESSAGES,
-  getNoticesForRule,
-  getRuleNoticeLines,
-} from '../../tools/rule-notices';
+import { MESSAGES, getNoticesForRule } from '../../tools/rule-notices';
 
 const numberOfRules = 50;
 const ruleNames = Object.keys(plugin.rules);
@@ -88,22 +83,6 @@ describe('rules', () => {
       const rule = plugin.rules[ruleName];
       const documentPath = join('docs', 'rules', `${ruleName}.md`);
       const documentContents = readFileSync(documentPath, 'utf8');
-      const documentLines = documentContents.split(EOL);
-
-      // Check title.
-      const expectedTitle = `# ${rule.meta.docs.description} (\`${ruleName}\`)`;
-
-      expect(documentLines[0]).toStrictEqual(expectedTitle);
-
-      // Ensure that expected notices are present in the correct order.
-      const noticeLines = getRuleNoticeLines(ruleName);
-      const NOTICE_START_LINE = 3;
-
-      noticeLines.forEach((noticeLine, index) =>
-        expect(documentLines[index + NOTICE_START_LINE]).toStrictEqual(
-          noticeLine,
-        ),
-      );
 
       // Ensure that unexpected notices are not present.
       const { unexpectedNotices } = getNoticesForRule(rule);
@@ -112,7 +91,7 @@ describe('rules', () => {
         expect(documentContents).not.toContain(MESSAGES[unexpectedNotice]),
       );
 
-      // Check for Rule details section.
+      // Check for a "Rule details" section.
       expect(documentContents).toContain('## Rule details');
 
       // Check if the rule has configuration options.
@@ -121,7 +100,7 @@ describe('rules', () => {
         (typeof rule.meta.schema === 'object' &&
           Object.keys(rule.meta.schema).length > 0)
       ) {
-        // Should have an options section header:
+        // Should have an "Options" section header:
         expect(documentContents).toContain('## Options');
       } else {
         // Should NOT have any options section header:
diff --git a/tools/regenerate-docs.ts b/tools/regenerate-docs.ts
index 8cfcd6d01..fe21cb278 100644
--- a/tools/regenerate-docs.ts
+++ b/tools/regenerate-docs.ts
@@ -6,11 +6,11 @@ import { TSESLint } from '@typescript-eslint/utils';
 import prettier, { Options } from 'prettier';
 import { prettier as prettierRC } from '../package.json';
 import plugin from '../src/index';
-import {
-  RULE_NOTICE_MARK_END,
-  RULE_NOTICE_MARK_START,
-  getRuleNoticeLines,
-} from './rule-notices';
+import { getRuleNoticeLines } from './rule-notices';
+
+// Marker so that rule doc header (title/notices) can be automatically updated.
+export const END_RULE_HEADER_MARKER =
+  '<!-- end rule header - generated by `yarn tools:regenerate-docs` -->';
 
 const pathTo = {
   readme: path.resolve(__dirname, '../README.md'),
@@ -99,28 +99,21 @@ const updateRulesList = (
   ].join('\n');
 };
 
-const updateRuleNotices = (contents, ruleName) => {
-  // Determine where to insert rule notices.
-  let ruleNoticeMarkStartLine = contents.findIndex(
-    line => line === RULE_NOTICE_MARK_START,
-  );
-  let ruleNoticeMarkEndLine = contents.findIndex(
-    line => line === RULE_NOTICE_MARK_END,
-  );
+const generateRuleHeaderLines = (description, name) => {
+  const lines = [`# ${description} (\`${name}\`)`];
 
-  // Add rule notice markers if they don't exist
-  if (ruleNoticeMarkStartLine === -1) {
-    contents.splice(2, 0, RULE_NOTICE_MARK_START, RULE_NOTICE_MARK_END);
-    ruleNoticeMarkStartLine = 2;
-    ruleNoticeMarkEndLine = 3;
-  }
+  lines.push(...getRuleNoticeLines(name));
 
-  // Insert rule notices between markers.
-  contents.splice(
-    ruleNoticeMarkStartLine + 1,
-    ruleNoticeMarkEndLine - ruleNoticeMarkStartLine - 1,
-    ...getRuleNoticeLines(ruleName),
-  );
+  lines.push(END_RULE_HEADER_MARKER);
+
+  return lines;
+};
+
+const replaceOrCreateHeader = (lines, newHeaderLines, marker) => {
+  const markerLineIndex = lines.findIndex(line => line === marker);
+
+  // Replace header section (or create at top if missing).
+  lines.splice(0, markerLineIndex + 1, ...newHeaderLines);
 };
 
 // copied from https://github.com/babel/babel/blob/d8da63c929f2d28c401571e2a43166678c555bc4/packages/babel-helpers/src/helpers.js#L602-L606
@@ -158,14 +151,14 @@ const details: RuleDetails[] = Object.keys(plugin.rules)
 details.forEach(({ name, description }) => {
   const pathToDoc = path.join(pathTo.docs, 'rules', `${name}.md`);
 
-  const contents = fs.readFileSync(pathToDoc).toString().split('\n');
+  const lines = fs.readFileSync(pathToDoc).toString().split('\n');
 
-  // Replace the title.
-  contents[0] = `# ${description} (\`${name}\`)`;
+  // Regenerate the header (title/notices) of each rule doc.
+  const newHeaderLines = generateRuleHeaderLines(description, name);
 
-  updateRuleNotices(contents, name);
+  replaceOrCreateHeader(lines, newHeaderLines, END_RULE_HEADER_MARKER);
 
-  fs.writeFileSync(pathToDoc, format(contents.join('\n')));
+  fs.writeFileSync(pathToDoc, format(lines.join('\n')));
 });
 
 const [baseRules, typeRules] = details.reduce<[RuleDetails[], RuleDetails[]]>(
diff --git a/tools/rule-notices.ts b/tools/rule-notices.ts
index 620028d44..87c6d7e6e 100644
--- a/tools/rule-notices.ts
+++ b/tools/rule-notices.ts
@@ -1,10 +1,5 @@
 import plugin from '../src';
 
-// Markers so that notices and be automatically generated and written to rule doc.
-export const RULE_NOTICE_MARK_START =
-  '<!-- begin rules notice -- generated by `yarn tools:regenerate-docs` -->';
-export const RULE_NOTICE_MARK_END = '<!-- end rules notice -->';
-
 enum MESSAGE_TYPE {
   CONFIGS = 1,
   DEPRECATED = 2,
@@ -22,8 +17,6 @@ export const MESSAGES = {
     '💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.',
 };
 
-const PRETTIER_MAX_LINE_LENGTH = 80;
-
 type RuleName = keyof typeof plugin.rules;
 type Rule = typeof plugin.rules[RuleName];
 
@@ -104,11 +97,6 @@ export function getRuleNoticeLines(ruleName: RuleName) {
     } else {
       lines.push(MESSAGES[expectedNotice]);
     }
-
-    if (lines[lines.length - 1].length > PRETTIER_MAX_LINE_LENGTH) {
-      // Insert Prettier ignore comment so that the notice doesn't get split onto multiple lines.
-      lines.splice(lines.length - 1, 0, '<!-- prettier-ignore -->');
-    }
   });
 
   return lines;

From c8a8c634c22d1bf9ebb707a4e35d7dd625f83e1d Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Mon, 5 Sep 2022 14:11:07 -0400
Subject: [PATCH 08/23] docs: add more comments

---
 tools/regenerate-docs.ts | 13 +++++++++++++
 tools/rule-notices.ts    |  6 ++++++
 2 files changed, 19 insertions(+)

diff --git a/tools/regenerate-docs.ts b/tools/regenerate-docs.ts
index fe21cb278..c21c5e232 100644
--- a/tools/regenerate-docs.ts
+++ b/tools/regenerate-docs.ts
@@ -99,6 +99,12 @@ const updateRulesList = (
   ].join('\n');
 };
 
+/**
+ * Generate a rule doc header for a particular rule.
+ * @param description - rule description
+ * @param name - rule name
+ * @returns {string[]} - lines for new header including marker
+ */
 const generateRuleHeaderLines = (description, name) => {
   const lines = [`# ${description} (\`${name}\`)`];
 
@@ -109,6 +115,13 @@ const generateRuleHeaderLines = (description, name) => {
   return lines;
 };
 
+/**
+ * Replace the header of a doc up to and including the specified marker.
+ * Insert at beginning if header doesn't exist.
+ * @param lines - lines of doc
+ * @param newHeaderLines - lines of new header including marker
+ * @param marker - marker to indicate end of header
+ */
 const replaceOrCreateHeader = (lines, newHeaderLines, marker) => {
   const markerLineIndex = lines.findIndex(line => line === marker);
 
diff --git a/tools/rule-notices.ts b/tools/rule-notices.ts
index 87c6d7e6e..c495f8589 100644
--- a/tools/rule-notices.ts
+++ b/tools/rule-notices.ts
@@ -20,6 +20,9 @@ export const MESSAGES = {
 type RuleName = keyof typeof plugin.rules;
 type Rule = typeof plugin.rules[RuleName];
 
+/**
+ * Get config names that a given rule belongs to.
+ */
 function getConfigsForRule(ruleName: RuleName) {
   const { configs } = plugin;
   const configNames: Array<keyof typeof configs> = [];
@@ -40,6 +43,9 @@ function getConfigsForRule(ruleName: RuleName) {
   return configNames.sort();
 }
 
+/**
+ * Convert list of configs to formatted string list.
+ */
 function configNamesToList(configNames: string[]) {
   return `\`${configNames.join('`, `')}\``;
 }

From c32829877b28fbb7b82b3ac0d66cb979d7df1cf0 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Mon, 5 Sep 2022 14:21:27 -0400
Subject: [PATCH 09/23] chore: test coverage ignore tools

---
 package.json | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/package.json b/package.json
index ac1e7669b..ade1292e4 100644
--- a/package.json
+++ b/package.json
@@ -81,6 +81,9 @@
           "<rootDir>/lib/.*",
           "<rootDir>/src/rules/__tests__/fixtures/*",
           "<rootDir>/src/rules/__tests__/test-utils.ts"
+        ],
+        "coveragePathIgnorePatterns": [
+          "<rootDir>/tools/"
         ]
       },
       {

From cbaa90912cc29c432964bda1dd03f2db5e82c01d Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Mon, 5 Sep 2022 16:59:17 -0400
Subject: [PATCH 10/23] docs: remove generated by comment

---
 docs/rules/consistent-test-it.md            | 2 +-
 docs/rules/expect-expect.md                 | 2 +-
 docs/rules/max-expects.md                   | 2 +-
 docs/rules/max-nested-describe.md           | 2 +-
 docs/rules/no-alias-methods.md              | 2 +-
 docs/rules/no-commented-out-tests.md        | 2 +-
 docs/rules/no-conditional-expect.md         | 2 +-
 docs/rules/no-conditional-in-test.md        | 2 +-
 docs/rules/no-deprecated-functions.md       | 2 +-
 docs/rules/no-disabled-tests.md             | 2 +-
 docs/rules/no-done-callback.md              | 2 +-
 docs/rules/no-duplicate-hooks.md            | 2 +-
 docs/rules/no-export.md                     | 2 +-
 docs/rules/no-focused-tests.md              | 2 +-
 docs/rules/no-hooks.md                      | 2 +-
 docs/rules/no-identical-title.md            | 2 +-
 docs/rules/no-if.md                         | 2 +-
 docs/rules/no-interpolation-in-snapshots.md | 2 +-
 docs/rules/no-jasmine-globals.md            | 2 +-
 docs/rules/no-large-snapshots.md            | 2 +-
 docs/rules/no-mocks-import.md               | 2 +-
 docs/rules/no-restricted-matchers.md        | 2 +-
 docs/rules/no-standalone-expect.md          | 2 +-
 docs/rules/no-test-prefixes.md              | 2 +-
 docs/rules/no-test-return-statement.md      | 2 +-
 docs/rules/prefer-called-with.md            | 2 +-
 docs/rules/prefer-comparison-matcher.md     | 2 +-
 docs/rules/prefer-each.md                   | 2 +-
 docs/rules/prefer-equality-matcher.md       | 2 +-
 docs/rules/prefer-expect-assertions.md      | 2 +-
 docs/rules/prefer-expect-resolves.md        | 2 +-
 docs/rules/prefer-hooks-in-order.md         | 2 +-
 docs/rules/prefer-hooks-on-top.md           | 2 +-
 docs/rules/prefer-lowercase-title.md        | 2 +-
 docs/rules/prefer-mock-promise-shorthand.md | 2 +-
 docs/rules/prefer-snapshot-hint.md          | 2 +-
 docs/rules/prefer-spy-on.md                 | 2 +-
 docs/rules/prefer-strict-equal.md           | 2 +-
 docs/rules/prefer-to-be.md                  | 2 +-
 docs/rules/prefer-to-contain.md             | 2 +-
 docs/rules/prefer-to-have-length.md         | 2 +-
 docs/rules/prefer-todo.md                   | 2 +-
 docs/rules/require-hook.md                  | 2 +-
 docs/rules/require-to-throw-message.md      | 2 +-
 docs/rules/require-top-level-describe.md    | 2 +-
 docs/rules/unbound-method.md                | 2 +-
 docs/rules/valid-describe-callback.md       | 2 +-
 docs/rules/valid-expect-in-promise.md       | 2 +-
 docs/rules/valid-expect.md                  | 2 +-
 docs/rules/valid-title.md                   | 2 +-
 tools/regenerate-docs.ts                    | 3 +--
 51 files changed, 51 insertions(+), 52 deletions(-)

diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md
index 93232e773..5b3ab48c5 100644
--- a/docs/rules/consistent-test-it.md
+++ b/docs/rules/consistent-test-it.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- 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:
diff --git a/docs/rules/expect-expect.md b/docs/rules/expect-expect.md
index b5679dc46..d6d1bb514 100644
--- a/docs/rules/expect-expect.md
+++ b/docs/rules/expect-expect.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Ensure that there is at least one `expect` call made in a test.
 
diff --git a/docs/rules/max-expects.md b/docs/rules/max-expects.md
index 80c2c7bb5..5c428a947 100644
--- a/docs/rules/max-expects.md
+++ b/docs/rules/max-expects.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- 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
diff --git a/docs/rules/max-nested-describe.md b/docs/rules/max-nested-describe.md
index 0aff77a04..4fce3d01a 100644
--- a/docs/rules/max-nested-describe.md
+++ b/docs/rules/max-nested-describe.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- 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
diff --git a/docs/rules/no-alias-methods.md b/docs/rules/no-alias-methods.md
index 554e041c3..3fe3f43b5 100644
--- a/docs/rules/no-alias-methods.md
+++ b/docs/rules/no-alias-methods.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- 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
diff --git a/docs/rules/no-commented-out-tests.md b/docs/rules/no-commented-out-tests.md
index 518a6708e..0a8c54093 100644
--- a/docs/rules/no-commented-out-tests.md
+++ b/docs/rules/no-commented-out-tests.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 This rule raises a warning about commented out tests. It's similar to
 no-disabled-tests rule.
diff --git a/docs/rules/no-conditional-expect.md b/docs/rules/no-conditional-expect.md
index be7861e9e..e6597a7b3 100644
--- a/docs/rules/no-conditional-expect.md
+++ b/docs/rules/no-conditional-expect.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`, `recommended`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 This rule prevents the use of `expect` in conditional blocks, such as `if`s &
 `catch`s.
diff --git a/docs/rules/no-conditional-in-test.md b/docs/rules/no-conditional-in-test.md
index 9903b117d..9b5438889 100644
--- a/docs/rules/no-conditional-in-test.md
+++ b/docs/rules/no-conditional-in-test.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- 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
diff --git a/docs/rules/no-deprecated-functions.md b/docs/rules/no-deprecated-functions.md
index 011d9b9e4..a4b9344b8 100644
--- a/docs/rules/no-deprecated-functions.md
+++ b/docs/rules/no-deprecated-functions.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- 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.
diff --git a/docs/rules/no-disabled-tests.md b/docs/rules/no-disabled-tests.md
index 4096e642e..f9ae99873 100644
--- a/docs/rules/no-disabled-tests.md
+++ b/docs/rules/no-disabled-tests.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- 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
diff --git a/docs/rules/no-done-callback.md b/docs/rules/no-done-callback.md
index 0ab5b5b29..06f6c2e21 100644
--- a/docs/rules/no-done-callback.md
+++ b/docs/rules/no-done-callback.md
@@ -8,7 +8,7 @@
 [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
 that can be applied manually.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- 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.
diff --git a/docs/rules/no-duplicate-hooks.md b/docs/rules/no-duplicate-hooks.md
index 210286fff..5038849fb 100644
--- a/docs/rules/no-duplicate-hooks.md
+++ b/docs/rules/no-duplicate-hooks.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 A `describe` block should not contain duplicate hooks.
 
diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md
index 3ac6a8f10..8b62f2495 100644
--- a/docs/rules/no-export.md
+++ b/docs/rules/no-export.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`, `recommended`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Prevents using `exports` if a file has one or more tests in it.
 
diff --git a/docs/rules/no-focused-tests.md b/docs/rules/no-focused-tests.md
index 9bedfe2e3..1953d84f0 100644
--- a/docs/rules/no-focused-tests.md
+++ b/docs/rules/no-focused-tests.md
@@ -8,7 +8,7 @@
 [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
 that can be applied manually.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 <!-- prettier-ignore -->
 Jest has a feature that allows you to focus tests by appending `.only` or
diff --git a/docs/rules/no-hooks.md b/docs/rules/no-hooks.md
index 93a9cb147..eadbdd08e 100644
--- a/docs/rules/no-hooks.md
+++ b/docs/rules/no-hooks.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- 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
diff --git a/docs/rules/no-identical-title.md b/docs/rules/no-identical-title.md
index 4fca9551f..8a1bc89b2 100644
--- a/docs/rules/no-identical-title.md
+++ b/docs/rules/no-identical-title.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`, `recommended`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- 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
diff --git a/docs/rules/no-if.md b/docs/rules/no-if.md
index 195559173..87f0562bd 100644
--- a/docs/rules/no-if.md
+++ b/docs/rules/no-if.md
@@ -2,7 +2,7 @@
 
 ❌ This rule is deprecated.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 This rule has been deprecated in favor of
 [`no-conditional-in-test`](no-conditional-in-test.md).
diff --git a/docs/rules/no-interpolation-in-snapshots.md b/docs/rules/no-interpolation-in-snapshots.md
index 62787601c..58c73c005 100644
--- a/docs/rules/no-interpolation-in-snapshots.md
+++ b/docs/rules/no-interpolation-in-snapshots.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`, `recommended`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Prevents the use of string interpolations in snapshots.
 
diff --git a/docs/rules/no-jasmine-globals.md b/docs/rules/no-jasmine-globals.md
index cb9b7e2ac..3df934a7d 100644
--- a/docs/rules/no-jasmine-globals.md
+++ b/docs/rules/no-jasmine-globals.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- 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
diff --git a/docs/rules/no-large-snapshots.md b/docs/rules/no-large-snapshots.md
index 70bd0bdb0..5e84af925 100644
--- a/docs/rules/no-large-snapshots.md
+++ b/docs/rules/no-large-snapshots.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- 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
diff --git a/docs/rules/no-mocks-import.md b/docs/rules/no-mocks-import.md
index 56bf927e5..c0d1a179c 100644
--- a/docs/rules/no-mocks-import.md
+++ b/docs/rules/no-mocks-import.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`, `recommended`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 When using `jest.mock`, your tests (just like the code being tested) should
 import from `./x`, not `./__mocks__/x`. Not following this rule can lead to
diff --git a/docs/rules/no-restricted-matchers.md b/docs/rules/no-restricted-matchers.md
index 3ea5042bc..f1e5ce0aa 100644
--- a/docs/rules/no-restricted-matchers.md
+++ b/docs/rules/no-restricted-matchers.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 You may want to ban specific matchers & modifiers from being used.
 
diff --git a/docs/rules/no-standalone-expect.md b/docs/rules/no-standalone-expect.md
index f2a9b5844..d3cadb342 100644
--- a/docs/rules/no-standalone-expect.md
+++ b/docs/rules/no-standalone-expect.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`, `recommended`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Prevents `expect` statements outside of a `test` or `it` block. An `expect`
 within a helper function (but outside of a `test` or `it` block) will not
diff --git a/docs/rules/no-test-prefixes.md b/docs/rules/no-test-prefixes.md
index 29fe3d639..83ab2ea5a 100644
--- a/docs/rules/no-test-prefixes.md
+++ b/docs/rules/no-test-prefixes.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Jest allows you to choose how you want to define focused and skipped tests, with
 multiple permutations for each:
diff --git a/docs/rules/no-test-return-statement.md b/docs/rules/no-test-return-statement.md
index b21ac8102..20a1d9b64 100644
--- a/docs/rules/no-test-return-statement.md
+++ b/docs/rules/no-test-return-statement.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Tests in Jest should be void and not return values.
 
diff --git a/docs/rules/prefer-called-with.md b/docs/rules/prefer-called-with.md
index 5e599cc47..cd20a261a 100644
--- a/docs/rules/prefer-called-with.md
+++ b/docs/rules/prefer-called-with.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 The `toBeCalled()` matcher is used to assert that a mock function has been
 called one or more times, without checking the arguments passed. The assertion
diff --git a/docs/rules/prefer-comparison-matcher.md b/docs/rules/prefer-comparison-matcher.md
index 9d83630f6..cc4cd516c 100644
--- a/docs/rules/prefer-comparison-matcher.md
+++ b/docs/rules/prefer-comparison-matcher.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Jest has a number of built-in matchers for comparing numbers, which allow for
 more readable tests and error messages if an expectation fails.
diff --git a/docs/rules/prefer-each.md b/docs/rules/prefer-each.md
index 3a5591bdf..be8b4a226 100644
--- a/docs/rules/prefer-each.md
+++ b/docs/rules/prefer-each.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Reports where you might be able to use `.each` instead of native loops.
 
diff --git a/docs/rules/prefer-equality-matcher.md b/docs/rules/prefer-equality-matcher.md
index e51e10049..9fc0a037c 100644
--- a/docs/rules/prefer-equality-matcher.md
+++ b/docs/rules/prefer-equality-matcher.md
@@ -8,7 +8,7 @@
 [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
 that can be applied manually.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Jest has built-in matchers for expecting equality, which allow for more readable
 tests and error messages if an expectation fails.
diff --git a/docs/rules/prefer-expect-assertions.md b/docs/rules/prefer-expect-assertions.md
index 9265fd2a0..7553e3441 100644
--- a/docs/rules/prefer-expect-assertions.md
+++ b/docs/rules/prefer-expect-assertions.md
@@ -8,7 +8,7 @@
 [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
 that can be applied manually.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Ensure every test to have either `expect.assertions(<number of assertions>)` OR
 `expect.hasAssertions()` as its first expression.
diff --git a/docs/rules/prefer-expect-resolves.md b/docs/rules/prefer-expect-resolves.md
index 65d352bc7..0a1f609c7 100644
--- a/docs/rules/prefer-expect-resolves.md
+++ b/docs/rules/prefer-expect-resolves.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 When working with promises, there are two primary ways you can test the resolved
 value:
diff --git a/docs/rules/prefer-hooks-in-order.md b/docs/rules/prefer-hooks-in-order.md
index ded06b160..d02704fd1 100644
--- a/docs/rules/prefer-hooks-in-order.md
+++ b/docs/rules/prefer-hooks-in-order.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 While hooks can be setup in any order, they're always called by `jest` in this
 specific order:
diff --git a/docs/rules/prefer-hooks-on-top.md b/docs/rules/prefer-hooks-on-top.md
index 499679b9d..7665b7911 100644
--- a/docs/rules/prefer-hooks-on-top.md
+++ b/docs/rules/prefer-hooks-on-top.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 While hooks can be setup anywhere in a test file, they are always called in a
 specific order, which means it can be confusing if they're intermixed with test
diff --git a/docs/rules/prefer-lowercase-title.md b/docs/rules/prefer-lowercase-title.md
index 87149cfe8..f765c852c 100644
--- a/docs/rules/prefer-lowercase-title.md
+++ b/docs/rules/prefer-lowercase-title.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 ## Rule details
 
diff --git a/docs/rules/prefer-mock-promise-shorthand.md b/docs/rules/prefer-mock-promise-shorthand.md
index 6e8ae0829..0695295d3 100644
--- a/docs/rules/prefer-mock-promise-shorthand.md
+++ b/docs/rules/prefer-mock-promise-shorthand.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 When working with mocks of functions that return promises, Jest provides some
 API sugar functions to reduce the amount of boilerplate you have to write.
diff --git a/docs/rules/prefer-snapshot-hint.md b/docs/rules/prefer-snapshot-hint.md
index 621707bf7..6d8818b51 100644
--- a/docs/rules/prefer-snapshot-hint.md
+++ b/docs/rules/prefer-snapshot-hint.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 When working with external snapshot matchers it's considered best practice to
 provide a hint (as the last argument to the matcher) describing the expected
diff --git a/docs/rules/prefer-spy-on.md b/docs/rules/prefer-spy-on.md
index ede3d1712..1bf4a5a9f 100644
--- a/docs/rules/prefer-spy-on.md
+++ b/docs/rules/prefer-spy-on.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 When mocking a function by overwriting a property you have to manually restore
 the original implementation when cleaning up. When using `jest.spyOn()` Jest
diff --git a/docs/rules/prefer-strict-equal.md b/docs/rules/prefer-strict-equal.md
index e86628950..2dd6d41b2 100644
--- a/docs/rules/prefer-strict-equal.md
+++ b/docs/rules/prefer-strict-equal.md
@@ -8,7 +8,7 @@
 [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
 that can be applied manually.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 `toStrictEqual` not only checks that two objects contain the same data but also
 that they have the same structure. It is common to expect objects to not only
diff --git a/docs/rules/prefer-to-be.md b/docs/rules/prefer-to-be.md
index 0d30a7f94..58d012df0 100644
--- a/docs/rules/prefer-to-be.md
+++ b/docs/rules/prefer-to-be.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 When asserting against primitive literals such as numbers and strings, the
 equality matchers all operate the same, but read slightly differently in code.
diff --git a/docs/rules/prefer-to-contain.md b/docs/rules/prefer-to-contain.md
index e4da2110d..a4116b8e1 100644
--- a/docs/rules/prefer-to-contain.md
+++ b/docs/rules/prefer-to-contain.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 In order to have a better failure message, `toContain()` should be used upon
 asserting expectations on an array containing an object.
diff --git a/docs/rules/prefer-to-have-length.md b/docs/rules/prefer-to-have-length.md
index 6ea672e90..d167eb9d2 100644
--- a/docs/rules/prefer-to-have-length.md
+++ b/docs/rules/prefer-to-have-length.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 In order to have a better failure message, `toHaveLength()` should be used upon
 asserting expectations on objects length property.
diff --git a/docs/rules/prefer-todo.md b/docs/rules/prefer-todo.md
index 1b2629912..5361b3513 100644
--- a/docs/rules/prefer-todo.md
+++ b/docs/rules/prefer-todo.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 When test cases are empty then it is better to mark them as `test.todo` as it
 will be highlighted in the summary output.
diff --git a/docs/rules/require-hook.md b/docs/rules/require-hook.md
index c98fb8561..e59ba1da2 100644
--- a/docs/rules/require-hook.md
+++ b/docs/rules/require-hook.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Often while writing tests you have some setup work that needs to happen before
 tests run, and you have some finishing work that needs to happen after tests
diff --git a/docs/rules/require-to-throw-message.md b/docs/rules/require-to-throw-message.md
index 77c4598a7..9e89f53d7 100644
--- a/docs/rules/require-to-throw-message.md
+++ b/docs/rules/require-to-throw-message.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 `toThrow()` (and its alias `toThrowError()`) is used to check if an error is
 thrown by a function call, such as in `expect(() => a()).toThrow()`. However, if
diff --git a/docs/rules/require-top-level-describe.md b/docs/rules/require-top-level-describe.md
index 5fb54cab1..1242f38d3 100644
--- a/docs/rules/require-top-level-describe.md
+++ b/docs/rules/require-top-level-describe.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Jest allows you to organise your test files the way you want it. However, the
 more your codebase grows, the more it becomes hard to navigate in your test
diff --git a/docs/rules/unbound-method.md b/docs/rules/unbound-method.md
index 6549a862e..3b282625f 100644
--- a/docs/rules/unbound-method.md
+++ b/docs/rules/unbound-method.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 ## Rule details
 
diff --git a/docs/rules/valid-describe-callback.md b/docs/rules/valid-describe-callback.md
index 30d4343f4..55e34a402 100644
--- a/docs/rules/valid-describe-callback.md
+++ b/docs/rules/valid-describe-callback.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`, `recommended`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Using an improper `describe()` callback function can lead to unexpected test
 errors.
diff --git a/docs/rules/valid-expect-in-promise.md b/docs/rules/valid-expect-in-promise.md
index 24469795e..bb8fc9bc9 100644
--- a/docs/rules/valid-expect-in-promise.md
+++ b/docs/rules/valid-expect-in-promise.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`, `recommended`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Ensure promises that include expectations are returned or awaited.
 
diff --git a/docs/rules/valid-expect.md b/docs/rules/valid-expect.md
index d8fd3142c..dee32269c 100644
--- a/docs/rules/valid-expect.md
+++ b/docs/rules/valid-expect.md
@@ -4,7 +4,7 @@
 [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
 `all`, `recommended`.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Ensure `expect()` is called with a single argument and there is an actual
 expectation made.
diff --git a/docs/rules/valid-title.md b/docs/rules/valid-title.md
index eb20fc2f1..1e7e15c93 100644
--- a/docs/rules/valid-title.md
+++ b/docs/rules/valid-title.md
@@ -8,7 +8,7 @@
 [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 on the command line.
 
-<!-- end rule header - generated by `yarn tools:regenerate-docs` -->
+<!-- end rule header -->
 
 Checks that the title of Jest blocks are valid by ensuring that titles are:
 
diff --git a/tools/regenerate-docs.ts b/tools/regenerate-docs.ts
index c21c5e232..a8c492af4 100644
--- a/tools/regenerate-docs.ts
+++ b/tools/regenerate-docs.ts
@@ -9,8 +9,7 @@ import plugin from '../src/index';
 import { getRuleNoticeLines } from './rule-notices';
 
 // Marker so that rule doc header (title/notices) can be automatically updated.
-export const END_RULE_HEADER_MARKER =
-  '<!-- end rule header - generated by `yarn tools:regenerate-docs` -->';
+export const END_RULE_HEADER_MARKER = '<!-- end rule header -->';
 
 const pathTo = {
   readme: path.resolve(__dirname, '../README.md'),

From 1529b66953ba5048b905801b246651648a5ba0bc Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Mon, 5 Sep 2022 17:04:04 -0400
Subject: [PATCH 11/23] refactor: address feedback

---
 tools/regenerate-docs.ts | 23 +++++++++++++----------
 tools/rule-notices.ts    |  4 ++--
 tsconfig.json            |  2 +-
 3 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/tools/regenerate-docs.ts b/tools/regenerate-docs.ts
index a8c492af4..50fdc54c4 100644
--- a/tools/regenerate-docs.ts
+++ b/tools/regenerate-docs.ts
@@ -104,15 +104,14 @@ const updateRulesList = (
  * @param name - rule name
  * @returns {string[]} - lines for new header including marker
  */
-const generateRuleHeaderLines = (description, name) => {
-  const lines = [`# ${description} (\`${name}\`)`];
-
-  lines.push(...getRuleNoticeLines(name));
-
-  lines.push(END_RULE_HEADER_MARKER);
-
-  return lines;
-};
+const generateRuleHeaderLines = (
+  description: string,
+  name: string,
+): string[] => [
+  `# ${description} (\`${name}\`)`,
+  ...getRuleNoticeLines(name),
+  END_RULE_HEADER_MARKER,
+];
 
 /**
  * Replace the header of a doc up to and including the specified marker.
@@ -121,7 +120,11 @@ const generateRuleHeaderLines = (description, name) => {
  * @param newHeaderLines - lines of new header including marker
  * @param marker - marker to indicate end of header
  */
-const replaceOrCreateHeader = (lines, newHeaderLines, marker) => {
+const replaceOrCreateHeader = (
+  lines: string[],
+  newHeaderLines: string[],
+  marker: string,
+) => {
   const markerLineIndex = lines.findIndex(line => line === marker);
 
   // Replace header section (or create at top if missing).
diff --git a/tools/rule-notices.ts b/tools/rule-notices.ts
index c495f8589..fb4e6093d 100644
--- a/tools/rule-notices.ts
+++ b/tools/rule-notices.ts
@@ -89,7 +89,7 @@ export function getRuleNoticeLines(ruleName: RuleName) {
 
   const { expectedNotices } = getNoticesForRule(plugin.rules[ruleName]);
 
-  expectedNotices.forEach(expectedNotice => {
+  for (const expectedNotice of expectedNotices) {
     lines.push(''); // Blank line first.
 
     if (expectedNotice === MESSAGE_TYPE.CONFIGS) {
@@ -103,7 +103,7 @@ export function getRuleNoticeLines(ruleName: RuleName) {
     } else {
       lines.push(MESSAGES[expectedNotice]);
     }
-  });
+  }
 
   return lines;
 }
diff --git a/tsconfig.json b/tsconfig.json
index 6c339a074..2b4f96ad5 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -11,5 +11,5 @@
     "resolveJsonModule": true,
     "forceConsistentCasingInFileNames": true
   },
-  "include": ["src/**/*"]
+  "include": ["src/**/*", "tools/**/*"]
 }

From 15f7add6fcc636ea779e9efacab5928d4d3191ba Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Mon, 5 Sep 2022 17:12:27 -0400
Subject: [PATCH 12/23] chore: remove tsconfig.json include for tools

---
 tsconfig.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tsconfig.json b/tsconfig.json
index 2b4f96ad5..6c339a074 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -11,5 +11,5 @@
     "resolveJsonModule": true,
     "forceConsistentCasingInFileNames": true
   },
-  "include": ["src/**/*", "tools/**/*"]
+  "include": ["src/**/*"]
 }

From c87c2db099cc86d86cca31032d148e9f8654f9cb Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Mon, 5 Sep 2022 17:16:22 -0400
Subject: [PATCH 13/23] refactor: remove RuleName type

---
 tools/rule-notices.ts | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/tools/rule-notices.ts b/tools/rule-notices.ts
index fb4e6093d..7d809b834 100644
--- a/tools/rule-notices.ts
+++ b/tools/rule-notices.ts
@@ -17,13 +17,12 @@ export const MESSAGES = {
     '💡 This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.',
 };
 
-type RuleName = keyof typeof plugin.rules;
-type Rule = typeof plugin.rules[RuleName];
+type Rule = typeof plugin.rules[string];
 
 /**
  * Get config names that a given rule belongs to.
  */
-function getConfigsForRule(ruleName: RuleName) {
+function getConfigsForRule(ruleName: string) {
   const { configs } = plugin;
   const configNames: Array<keyof typeof configs> = [];
   let configName: keyof typeof configs;
@@ -84,7 +83,7 @@ export function getNoticesForRule(rule: Rule) {
 /**
  * Get the lines for the notice section at the top of a rule doc.
  */
-export function getRuleNoticeLines(ruleName: RuleName) {
+export function getRuleNoticeLines(ruleName: string) {
   const lines: string[] = [];
 
   const { expectedNotices } = getNoticesForRule(plugin.rules[ruleName]);

From d966ec10ea7194d0a0fdeafad0a8e5375d1645ae Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Mon, 5 Sep 2022 20:25:23 -0400
Subject: [PATCH 14/23] refactor: getNoticesForRule should return object

---
 src/__tests__/rules.test.ts |  8 ------
 tools/rule-notices.ts       | 57 ++++++++++++++++---------------------
 2 files changed, 25 insertions(+), 40 deletions(-)

diff --git a/src/__tests__/rules.test.ts b/src/__tests__/rules.test.ts
index 7ce522205..8fde88c9e 100644
--- a/src/__tests__/rules.test.ts
+++ b/src/__tests__/rules.test.ts
@@ -1,7 +1,6 @@
 import { existsSync, readFileSync } from 'fs';
 import { join, resolve } from 'path';
 import plugin from '../';
-import { MESSAGES, getNoticesForRule } from '../../tools/rule-notices';
 
 const numberOfRules = 50;
 const ruleNames = Object.keys(plugin.rules);
@@ -84,13 +83,6 @@ describe('rules', () => {
       const documentPath = join('docs', 'rules', `${ruleName}.md`);
       const documentContents = readFileSync(documentPath, 'utf8');
 
-      // Ensure that unexpected notices are not present.
-      const { unexpectedNotices } = getNoticesForRule(rule);
-
-      unexpectedNotices.forEach(unexpectedNotice =>
-        expect(documentContents).not.toContain(MESSAGES[unexpectedNotice]),
-      );
-
       // Check for a "Rule details" section.
       expect(documentContents).toContain('## Rule details');
 
diff --git a/tools/rule-notices.ts b/tools/rule-notices.ts
index 7d809b834..f7ae7a357 100644
--- a/tools/rule-notices.ts
+++ b/tools/rule-notices.ts
@@ -1,10 +1,10 @@
 import plugin from '../src';
 
 enum MESSAGE_TYPE {
-  CONFIGS = 1,
-  DEPRECATED = 2,
-  FIXABLE = 3,
-  HAS_SUGGESTIONS = 4,
+  CONFIGS = 'configs',
+  DEPRECATED = 'deprecated',
+  FIXABLE = 'fixable',
+  HAS_SUGGESTIONS = 'hasSuggestions',
 }
 
 export const MESSAGES = {
@@ -53,31 +53,16 @@ function configNamesToList(configNames: string[]) {
  * Determine which notices should and should not be included at the top of a rule doc.
  */
 export function getNoticesForRule(rule: Rule) {
-  const expectedNotices: MESSAGE_TYPE[] = [];
-  const unexpectedNotices: MESSAGE_TYPE[] = [];
-
-  if (rule.meta.deprecated) {
-    expectedNotices.push(MESSAGE_TYPE.DEPRECATED);
-    unexpectedNotices.push(MESSAGE_TYPE.CONFIGS);
-  } else {
-    unexpectedNotices.push(MESSAGE_TYPE.DEPRECATED);
-    expectedNotices.push(MESSAGE_TYPE.CONFIGS);
-  }
-  if (rule.meta.fixable) {
-    expectedNotices.push(MESSAGE_TYPE.FIXABLE);
-  } else {
-    unexpectedNotices.push(MESSAGE_TYPE.FIXABLE);
-  }
-  if (rule.meta.hasSuggestions) {
-    expectedNotices.push(MESSAGE_TYPE.HAS_SUGGESTIONS);
-  } else {
-    unexpectedNotices.push(MESSAGE_TYPE.HAS_SUGGESTIONS);
-  }
-
-  return {
-    expectedNotices,
-    unexpectedNotices,
+  const notices: {
+    [key in MESSAGE_TYPE]: boolean;
+  } = {
+    [MESSAGE_TYPE.CONFIGS]: !rule.meta.deprecated,
+    [MESSAGE_TYPE.DEPRECATED]: rule.meta.deprecated || false,
+    [MESSAGE_TYPE.FIXABLE]: Boolean(rule.meta.fixable),
+    [MESSAGE_TYPE.HAS_SUGGESTIONS]: rule.meta.hasSuggestions || false,
   };
+
+  return notices;
 }
 
 /**
@@ -86,12 +71,20 @@ export function getNoticesForRule(rule: Rule) {
 export function getRuleNoticeLines(ruleName: string) {
   const lines: string[] = [];
 
-  const { expectedNotices } = getNoticesForRule(plugin.rules[ruleName]);
+  const notices = getNoticesForRule(plugin.rules[ruleName]);
+  let messageType: keyof typeof notices;
+
+  for (messageType in notices) {
+    const expected = notices[messageType];
+
+    if (!expected) {
+      // This notice should not be included.
+      continue;
+    }
 
-  for (const expectedNotice of expectedNotices) {
     lines.push(''); // Blank line first.
 
-    if (expectedNotice === MESSAGE_TYPE.CONFIGS) {
+    if (messageType === MESSAGE_TYPE.CONFIGS) {
       // This notice should have a list of the rule's configs.
       const configsEnabled = getConfigsForRule(ruleName);
       const message = `${MESSAGES[MESSAGE_TYPE.CONFIGS]} ${configNamesToList(
@@ -100,7 +93,7 @@ export function getRuleNoticeLines(ruleName: string) {
 
       lines.push(message);
     } else {
-      lines.push(MESSAGES[expectedNotice]);
+      lines.push(MESSAGES[messageType]);
     }
   }
 

From dd5a27486cacc918c8572bf33039f30da3065c80 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Mon, 5 Sep 2022 20:46:06 -0400
Subject: [PATCH 15/23] test: switch rule doc test to generator failure

---
 src/__tests__/rules.test.ts | 29 ++------------------------
 tools/regenerate-docs.ts    | 41 ++++++++++++++++++++++++++++++++++---
 2 files changed, 40 insertions(+), 30 deletions(-)

diff --git a/src/__tests__/rules.test.ts b/src/__tests__/rules.test.ts
index 8fde88c9e..a8c66cc18 100644
--- a/src/__tests__/rules.test.ts
+++ b/src/__tests__/rules.test.ts
@@ -1,5 +1,5 @@
-import { existsSync, readFileSync } from 'fs';
-import { join, resolve } from 'path';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
 import plugin from '../';
 
 const numberOfRules = 50;
@@ -76,29 +76,4 @@ describe('rules', () => {
       expect(() => require(`../rules/${ruleName}`)).not.toThrow();
     });
   });
-
-  describe('rule documentation files have the correct content', () => {
-    it.each(ruleNames)('%s', ruleName => {
-      const rule = plugin.rules[ruleName];
-      const documentPath = join('docs', 'rules', `${ruleName}.md`);
-      const documentContents = readFileSync(documentPath, 'utf8');
-
-      // Check for a "Rule details" section.
-      expect(documentContents).toContain('## Rule details');
-
-      // Check if the rule has configuration options.
-      if (
-        (Array.isArray(rule.meta.schema) && rule.meta.schema.length > 0) ||
-        (typeof rule.meta.schema === 'object' &&
-          Object.keys(rule.meta.schema).length > 0)
-      ) {
-        // Should have an "Options" section header:
-        expect(documentContents).toContain('## Options');
-      } else {
-        // Should NOT have any options section header:
-        expect(documentContents).not.toContain('## Options');
-        expect(documentContents).not.toContain('## Config');
-      }
-    });
-  });
 });
diff --git a/tools/regenerate-docs.ts b/tools/regenerate-docs.ts
index 50fdc54c4..95fc09f4c 100644
--- a/tools/regenerate-docs.ts
+++ b/tools/regenerate-docs.ts
@@ -28,6 +28,7 @@ interface RuleDetails {
   fixable: FixType | false;
   requiresTypeChecking: boolean;
   deprecated: boolean;
+  schema: any;
 }
 
 type RuleModule = TSESLint.RuleModule<string, unknown[]> & {
@@ -131,6 +132,30 @@ const replaceOrCreateHeader = (
   lines.splice(0, markerLineIndex + 1, ...newHeaderLines);
 };
 
+/**
+ * Ensure a rule doc contains (or doesn't contain) some particular content.
+ * Upon failure, output the failure and exit with failure.
+ * @param ruleName - which rule we are checking
+ * @param contents - the rule doc's contents
+ * @param content - the content we are checking for
+ * @param expected - whether the content should be present or not present
+ */
+const expectContent = (
+  ruleName: string,
+  contents: string,
+  content: string,
+  expected: boolean,
+) => {
+  if (contents.includes(content) !== expected) {
+    console.error(
+      `\`${ruleName}\` rule doc should ${
+        expected ? '' : 'not '
+      }have included: ${content}`,
+    );
+    process.exitCode = 1;
+  }
+};
+
 // copied from https://github.com/babel/babel/blob/d8da63c929f2d28c401571e2a43166678c555bc4/packages/babel-helpers/src/helpers.js#L602-L606
 /* istanbul ignore next */
 const interopRequireDefault = (obj: any): { default: any } =>
@@ -160,13 +185,14 @@ const details: RuleDetails[] = Object.keys(plugin.rules)
         : false,
       requiresTypeChecking: rule.meta.docs.requiresTypeChecking ?? false,
       deprecated: rule.meta.deprecated ?? false,
+      schema: rule.meta.schema,
     }),
   );
 
-details.forEach(({ name, description }) => {
+details.forEach(({ name, description, schema }) => {
   const pathToDoc = path.join(pathTo.docs, 'rules', `${name}.md`);
-
-  const lines = fs.readFileSync(pathToDoc).toString().split('\n');
+  const contents = fs.readFileSync(pathToDoc).toString();
+  const lines = contents.split('\n');
 
   // Regenerate the header (title/notices) of each rule doc.
   const newHeaderLines = generateRuleHeaderLines(description, name);
@@ -174,6 +200,15 @@ details.forEach(({ name, description }) => {
   replaceOrCreateHeader(lines, newHeaderLines, END_RULE_HEADER_MARKER);
 
   fs.writeFileSync(pathToDoc, format(lines.join('\n')));
+
+  // Check for potential issues with the rule doc.
+
+  const hasOptions =
+    (Array.isArray(schema) && schema.length > 0) ||
+    (typeof schema === 'object' && Object.keys(schema).length > 0);
+
+  expectContent(name, contents, '## Rule details', true);
+  expectContent(name, contents, '## Options', hasOptions);
 });
 
 const [baseRules, typeRules] = details.reduce<[RuleDetails[], RuleDetails[]]>(

From 86ca6b308edb2c91c330e6c0f164cf9af976e09a Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Mon, 5 Sep 2022 21:00:18 -0400
Subject: [PATCH 16/23] docs: fix comment

---
 tools/regenerate-docs.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/regenerate-docs.ts b/tools/regenerate-docs.ts
index 95fc09f4c..6b8fa8cea 100644
--- a/tools/regenerate-docs.ts
+++ b/tools/regenerate-docs.ts
@@ -134,7 +134,7 @@ const replaceOrCreateHeader = (
 
 /**
  * Ensure a rule doc contains (or doesn't contain) some particular content.
- * Upon failure, output the failure and exit with failure.
+ * Upon failure, output the failure and set a failure exit code.
  * @param ruleName - which rule we are checking
  * @param contents - the rule doc's contents
  * @param content - the content we are checking for

From a1b3f100b27a45bc2460da19bf9696d59f1d8fc6 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Tue, 6 Sep 2022 11:16:36 -0400
Subject: [PATCH 17/23] docs: deprecated rule notice show replaced by rules

---
 docs/rules/no-if.md   |  6 ++----
 tools/rule-notices.ts | 23 ++++++++++++++++++++---
 2 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/docs/rules/no-if.md b/docs/rules/no-if.md
index 87f0562bd..033a9c3a2 100644
--- a/docs/rules/no-if.md
+++ b/docs/rules/no-if.md
@@ -1,12 +1,10 @@
 # Disallow conditional logic (`no-if`)
 
-❌ This rule is deprecated.
+❌ This rule is deprecated. It was replaced by
+[no-conditional-in-test](no-conditional-in-test.md).
 
 <!-- end rule header -->
 
-This rule has been deprecated in favor of
-[`no-conditional-in-test`](no-conditional-in-test.md).
-
 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 an if statement will usually be better served by a test devoted
diff --git a/tools/rule-notices.ts b/tools/rule-notices.ts
index f7ae7a357..3762c70de 100644
--- a/tools/rule-notices.ts
+++ b/tools/rule-notices.ts
@@ -43,12 +43,19 @@ function getConfigsForRule(ruleName: string) {
 }
 
 /**
- * Convert list of configs to formatted string list.
+ * Convert list of configs to string list of formatted names.
  */
-function configNamesToList(configNames: string[]) {
+function configNamesToList(configNames: readonly string[]) {
   return `\`${configNames.join('`, `')}\``;
 }
 
+/**
+ * Convert list of rule names to string list of links.
+ */
+function rulesNamesToList(ruleNames: readonly string[]) {
+  return ruleNames.map(ruleName => `[${ruleName}](${ruleName}.md)`).join(', ');
+}
+
 /**
  * Determine which notices should and should not be included at the top of a rule doc.
  */
@@ -71,7 +78,8 @@ export function getNoticesForRule(rule: Rule) {
 export function getRuleNoticeLines(ruleName: string) {
   const lines: string[] = [];
 
-  const notices = getNoticesForRule(plugin.rules[ruleName]);
+  const rule = plugin.rules[ruleName];
+  const notices = getNoticesForRule(rule);
   let messageType: keyof typeof notices;
 
   for (messageType in notices) {
@@ -91,6 +99,15 @@ export function getRuleNoticeLines(ruleName: string) {
         configsEnabled,
       )}.`;
 
+      lines.push(message);
+    } else if (messageType === MESSAGE_TYPE.DEPRECATED) {
+      // This notice should include links to the replacement rule(s) if available.
+      const message = rule.meta.replacedBy
+        ? `${MESSAGES[messageType]} It was replaced by ${rulesNamesToList(
+            rule.meta.replacedBy,
+          )}.`
+        : MESSAGES[messageType];
+
       lines.push(message);
     } else {
       lines.push(MESSAGES[messageType]);

From c346d05411abe073f6e2e3ba0f506456fbbcfd8a Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Wed, 7 Sep 2022 10:19:01 -0400
Subject: [PATCH 18/23] chore: remove coveragePathIgnorePatterns

---
 package.json | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/package.json b/package.json
index ade1292e4..ac1e7669b 100644
--- a/package.json
+++ b/package.json
@@ -81,9 +81,6 @@
           "<rootDir>/lib/.*",
           "<rootDir>/src/rules/__tests__/fixtures/*",
           "<rootDir>/src/rules/__tests__/test-utils.ts"
-        ],
-        "coveragePathIgnorePatterns": [
-          "<rootDir>/tools/"
         ]
       },
       {

From 9c901b2e8793a7c2cce6de18fb7c69ffa28c6b9f Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Wed, 7 Sep 2022 10:20:44 -0400
Subject: [PATCH 19/23] docs: config link README

---
 docs/rules/consistent-test-it.md            | 2 +-
 docs/rules/expect-expect.md                 | 2 +-
 docs/rules/max-expects.md                   | 2 +-
 docs/rules/max-nested-describe.md           | 2 +-
 docs/rules/no-alias-methods.md              | 2 +-
 docs/rules/no-commented-out-tests.md        | 2 +-
 docs/rules/no-conditional-expect.md         | 2 +-
 docs/rules/no-conditional-in-test.md        | 2 +-
 docs/rules/no-deprecated-functions.md       | 2 +-
 docs/rules/no-disabled-tests.md             | 2 +-
 docs/rules/no-done-callback.md              | 2 +-
 docs/rules/no-duplicate-hooks.md            | 2 +-
 docs/rules/no-export.md                     | 2 +-
 docs/rules/no-focused-tests.md              | 2 +-
 docs/rules/no-hooks.md                      | 2 +-
 docs/rules/no-identical-title.md            | 2 +-
 docs/rules/no-interpolation-in-snapshots.md | 2 +-
 docs/rules/no-jasmine-globals.md            | 2 +-
 docs/rules/no-large-snapshots.md            | 2 +-
 docs/rules/no-mocks-import.md               | 2 +-
 docs/rules/no-restricted-matchers.md        | 2 +-
 docs/rules/no-standalone-expect.md          | 2 +-
 docs/rules/no-test-prefixes.md              | 2 +-
 docs/rules/no-test-return-statement.md      | 2 +-
 docs/rules/prefer-called-with.md            | 2 +-
 docs/rules/prefer-comparison-matcher.md     | 2 +-
 docs/rules/prefer-each.md                   | 2 +-
 docs/rules/prefer-equality-matcher.md       | 2 +-
 docs/rules/prefer-expect-assertions.md      | 2 +-
 docs/rules/prefer-expect-resolves.md        | 2 +-
 docs/rules/prefer-hooks-in-order.md         | 2 +-
 docs/rules/prefer-hooks-on-top.md           | 2 +-
 docs/rules/prefer-lowercase-title.md        | 2 +-
 docs/rules/prefer-mock-promise-shorthand.md | 2 +-
 docs/rules/prefer-snapshot-hint.md          | 2 +-
 docs/rules/prefer-spy-on.md                 | 2 +-
 docs/rules/prefer-strict-equal.md           | 2 +-
 docs/rules/prefer-to-be.md                  | 2 +-
 docs/rules/prefer-to-contain.md             | 2 +-
 docs/rules/prefer-to-have-length.md         | 2 +-
 docs/rules/prefer-todo.md                   | 2 +-
 docs/rules/require-hook.md                  | 2 +-
 docs/rules/require-to-throw-message.md      | 2 +-
 docs/rules/require-top-level-describe.md    | 2 +-
 docs/rules/unbound-method.md                | 2 +-
 docs/rules/valid-describe-callback.md       | 2 +-
 docs/rules/valid-expect-in-promise.md       | 2 +-
 docs/rules/valid-expect.md                  | 2 +-
 docs/rules/valid-title.md                   | 2 +-
 tools/rule-notices.ts                       | 2 +-
 50 files changed, 50 insertions(+), 50 deletions(-)

diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md
index 5b3ab48c5..71d303181 100644
--- a/docs/rules/consistent-test-it.md
+++ b/docs/rules/consistent-test-it.md
@@ -1,7 +1,7 @@
 # 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#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 🔧 This rule is automatically fixable using the `--fix`
diff --git a/docs/rules/expect-expect.md b/docs/rules/expect-expect.md
index d6d1bb514..f832faeb7 100644
--- a/docs/rules/expect-expect.md
+++ b/docs/rules/expect-expect.md
@@ -1,7 +1,7 @@
 # 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#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/max-expects.md b/docs/rules/max-expects.md
index 5c428a947..5034f4d4a 100644
--- a/docs/rules/max-expects.md
+++ b/docs/rules/max-expects.md
@@ -1,7 +1,7 @@
 # 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#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/max-nested-describe.md b/docs/rules/max-nested-describe.md
index 4fce3d01a..6293ae1a4 100644
--- a/docs/rules/max-nested-describe.md
+++ b/docs/rules/max-nested-describe.md
@@ -1,7 +1,7 @@
 # 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#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-alias-methods.md b/docs/rules/no-alias-methods.md
index 3fe3f43b5..fc61154c3 100644
--- a/docs/rules/no-alias-methods.md
+++ b/docs/rules/no-alias-methods.md
@@ -1,7 +1,7 @@
 # Disallow alias methods (`no-alias-methods`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[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`
diff --git a/docs/rules/no-commented-out-tests.md b/docs/rules/no-commented-out-tests.md
index 0a8c54093..413008d76 100644
--- a/docs/rules/no-commented-out-tests.md
+++ b/docs/rules/no-commented-out-tests.md
@@ -1,7 +1,7 @@
 # Disallow commented out tests (`no-commented-out-tests`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-conditional-expect.md b/docs/rules/no-conditional-expect.md
index e6597a7b3..b15dd68ab 100644
--- a/docs/rules/no-conditional-expect.md
+++ b/docs/rules/no-conditional-expect.md
@@ -1,7 +1,7 @@
 # Prevent calling `expect` conditionally (`no-conditional-expect`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `recommended`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-conditional-in-test.md b/docs/rules/no-conditional-in-test.md
index 9b5438889..7fe5e9c8f 100644
--- a/docs/rules/no-conditional-in-test.md
+++ b/docs/rules/no-conditional-in-test.md
@@ -1,7 +1,7 @@
 # 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#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-deprecated-functions.md b/docs/rules/no-deprecated-functions.md
index a4b9344b8..4b3a23909 100644
--- a/docs/rules/no-deprecated-functions.md
+++ b/docs/rules/no-deprecated-functions.md
@@ -1,7 +1,7 @@
 # Disallow use of deprecated functions (`no-deprecated-functions`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[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`
diff --git a/docs/rules/no-disabled-tests.md b/docs/rules/no-disabled-tests.md
index f9ae99873..56595ed55 100644
--- a/docs/rules/no-disabled-tests.md
+++ b/docs/rules/no-disabled-tests.md
@@ -1,7 +1,7 @@
 # Disallow disabled tests (`no-disabled-tests`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-done-callback.md b/docs/rules/no-done-callback.md
index 06f6c2e21..551fb9e0d 100644
--- a/docs/rules/no-done-callback.md
+++ b/docs/rules/no-done-callback.md
@@ -1,7 +1,7 @@
 # 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#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `recommended`.
 
 💡 This rule provides
diff --git a/docs/rules/no-duplicate-hooks.md b/docs/rules/no-duplicate-hooks.md
index 5038849fb..72bca8b31 100644
--- a/docs/rules/no-duplicate-hooks.md
+++ b/docs/rules/no-duplicate-hooks.md
@@ -1,7 +1,7 @@
 # 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#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md
index 8b62f2495..df9136be5 100644
--- a/docs/rules/no-export.md
+++ b/docs/rules/no-export.md
@@ -1,7 +1,7 @@
 # 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#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `recommended`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-focused-tests.md b/docs/rules/no-focused-tests.md
index 1953d84f0..02975a0b3 100644
--- a/docs/rules/no-focused-tests.md
+++ b/docs/rules/no-focused-tests.md
@@ -1,7 +1,7 @@
 # Disallow focused tests (`no-focused-tests`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `recommended`.
 
 💡 This rule provides
diff --git a/docs/rules/no-hooks.md b/docs/rules/no-hooks.md
index eadbdd08e..75438f4cb 100644
--- a/docs/rules/no-hooks.md
+++ b/docs/rules/no-hooks.md
@@ -1,7 +1,7 @@
 # Disallow setup and teardown hooks (`no-hooks`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-identical-title.md b/docs/rules/no-identical-title.md
index 8a1bc89b2..495b0faeb 100644
--- a/docs/rules/no-identical-title.md
+++ b/docs/rules/no-identical-title.md
@@ -1,7 +1,7 @@
 # Disallow identical titles (`no-identical-title`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `recommended`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-interpolation-in-snapshots.md b/docs/rules/no-interpolation-in-snapshots.md
index 58c73c005..a4a394614 100644
--- a/docs/rules/no-interpolation-in-snapshots.md
+++ b/docs/rules/no-interpolation-in-snapshots.md
@@ -1,7 +1,7 @@
 # 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#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `recommended`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-jasmine-globals.md b/docs/rules/no-jasmine-globals.md
index 3df934a7d..fb48142bb 100644
--- a/docs/rules/no-jasmine-globals.md
+++ b/docs/rules/no-jasmine-globals.md
@@ -1,7 +1,7 @@
 # Disallow Jasmine globals (`no-jasmine-globals`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[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`
diff --git a/docs/rules/no-large-snapshots.md b/docs/rules/no-large-snapshots.md
index 5e84af925..8a4d6e27e 100644
--- a/docs/rules/no-large-snapshots.md
+++ b/docs/rules/no-large-snapshots.md
@@ -1,7 +1,7 @@
 # disallow large snapshots (`no-large-snapshots`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-mocks-import.md b/docs/rules/no-mocks-import.md
index c0d1a179c..4c03ce549 100644
--- a/docs/rules/no-mocks-import.md
+++ b/docs/rules/no-mocks-import.md
@@ -1,7 +1,7 @@
 # Disallow manually importing from `__mocks__` (`no-mocks-import`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `recommended`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-restricted-matchers.md b/docs/rules/no-restricted-matchers.md
index f1e5ce0aa..c5efff6ad 100644
--- a/docs/rules/no-restricted-matchers.md
+++ b/docs/rules/no-restricted-matchers.md
@@ -1,7 +1,7 @@
 # Disallow specific matchers & modifiers (`no-restricted-matchers`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-standalone-expect.md b/docs/rules/no-standalone-expect.md
index d3cadb342..9152161b0 100644
--- a/docs/rules/no-standalone-expect.md
+++ b/docs/rules/no-standalone-expect.md
@@ -1,7 +1,7 @@
 # Disallow using `expect` outside of `it` or `test` blocks (`no-standalone-expect`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `recommended`.
 
 <!-- end rule header -->
diff --git a/docs/rules/no-test-prefixes.md b/docs/rules/no-test-prefixes.md
index 83ab2ea5a..5a9eaee97 100644
--- a/docs/rules/no-test-prefixes.md
+++ b/docs/rules/no-test-prefixes.md
@@ -1,7 +1,7 @@
 # Use `.only` and `.skip` over `f` and `x` (`no-test-prefixes`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[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`
diff --git a/docs/rules/no-test-return-statement.md b/docs/rules/no-test-return-statement.md
index 20a1d9b64..f5d6a1e53 100644
--- a/docs/rules/no-test-return-statement.md
+++ b/docs/rules/no-test-return-statement.md
@@ -1,7 +1,7 @@
 # Disallow explicitly returning from tests (`no-test-return-statement`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/prefer-called-with.md b/docs/rules/prefer-called-with.md
index cd20a261a..b9acf363b 100644
--- a/docs/rules/prefer-called-with.md
+++ b/docs/rules/prefer-called-with.md
@@ -1,7 +1,7 @@
 # Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` (`prefer-called-with`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/prefer-comparison-matcher.md b/docs/rules/prefer-comparison-matcher.md
index cc4cd516c..5f27ffce4 100644
--- a/docs/rules/prefer-comparison-matcher.md
+++ b/docs/rules/prefer-comparison-matcher.md
@@ -1,7 +1,7 @@
 # Suggest using the built-in comparison matchers (`prefer-comparison-matcher`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 🔧 This rule is automatically fixable using the `--fix`
diff --git a/docs/rules/prefer-each.md b/docs/rules/prefer-each.md
index be8b4a226..381a063c4 100644
--- a/docs/rules/prefer-each.md
+++ b/docs/rules/prefer-each.md
@@ -1,7 +1,7 @@
 # Prefer using `.each` rather than manual loops (`prefer-each`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/prefer-equality-matcher.md b/docs/rules/prefer-equality-matcher.md
index 9fc0a037c..afcec0356 100644
--- a/docs/rules/prefer-equality-matcher.md
+++ b/docs/rules/prefer-equality-matcher.md
@@ -1,7 +1,7 @@
 # Suggest using the built-in equality matchers (`prefer-equality-matcher`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 💡 This rule provides
diff --git a/docs/rules/prefer-expect-assertions.md b/docs/rules/prefer-expect-assertions.md
index 7553e3441..dd55676eb 100644
--- a/docs/rules/prefer-expect-assertions.md
+++ b/docs/rules/prefer-expect-assertions.md
@@ -1,7 +1,7 @@
 # Suggest using `expect.assertions()` OR `expect.hasAssertions()` (`prefer-expect-assertions`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 💡 This rule provides
diff --git a/docs/rules/prefer-expect-resolves.md b/docs/rules/prefer-expect-resolves.md
index 0a1f609c7..bdb2baacd 100644
--- a/docs/rules/prefer-expect-resolves.md
+++ b/docs/rules/prefer-expect-resolves.md
@@ -1,7 +1,7 @@
 # Prefer `await expect(...).resolves` over `expect(await ...)` syntax (`prefer-expect-resolves`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 🔧 This rule is automatically fixable using the `--fix`
diff --git a/docs/rules/prefer-hooks-in-order.md b/docs/rules/prefer-hooks-in-order.md
index d02704fd1..d24e21957 100644
--- a/docs/rules/prefer-hooks-in-order.md
+++ b/docs/rules/prefer-hooks-in-order.md
@@ -1,7 +1,7 @@
 # Prefer having hooks in a consistent order (`prefer-hooks-in-order`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/prefer-hooks-on-top.md b/docs/rules/prefer-hooks-on-top.md
index 7665b7911..74a36ed0d 100644
--- a/docs/rules/prefer-hooks-on-top.md
+++ b/docs/rules/prefer-hooks-on-top.md
@@ -1,7 +1,7 @@
 # Suggest having hooks before any test cases (`prefer-hooks-on-top`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/prefer-lowercase-title.md b/docs/rules/prefer-lowercase-title.md
index f765c852c..742481a55 100644
--- a/docs/rules/prefer-lowercase-title.md
+++ b/docs/rules/prefer-lowercase-title.md
@@ -1,7 +1,7 @@
 # Enforce lowercase test names (`prefer-lowercase-title`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 🔧 This rule is automatically fixable using the `--fix`
diff --git a/docs/rules/prefer-mock-promise-shorthand.md b/docs/rules/prefer-mock-promise-shorthand.md
index 0695295d3..90d3ef62d 100644
--- a/docs/rules/prefer-mock-promise-shorthand.md
+++ b/docs/rules/prefer-mock-promise-shorthand.md
@@ -1,7 +1,7 @@
 # Prefer mock resolved/rejected shorthands for promises (`prefer-mock-promise-shorthand`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 🔧 This rule is automatically fixable using the `--fix`
diff --git a/docs/rules/prefer-snapshot-hint.md b/docs/rules/prefer-snapshot-hint.md
index 6d8818b51..d6f91666d 100644
--- a/docs/rules/prefer-snapshot-hint.md
+++ b/docs/rules/prefer-snapshot-hint.md
@@ -1,7 +1,7 @@
 # Prefer including a hint with external snapshots (`prefer-snapshot-hint`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/prefer-spy-on.md b/docs/rules/prefer-spy-on.md
index 1bf4a5a9f..7a3d071e3 100644
--- a/docs/rules/prefer-spy-on.md
+++ b/docs/rules/prefer-spy-on.md
@@ -1,7 +1,7 @@
 # Suggest using `jest.spyOn()` (`prefer-spy-on`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 🔧 This rule is automatically fixable using the `--fix`
diff --git a/docs/rules/prefer-strict-equal.md b/docs/rules/prefer-strict-equal.md
index 2dd6d41b2..1e4689027 100644
--- a/docs/rules/prefer-strict-equal.md
+++ b/docs/rules/prefer-strict-equal.md
@@ -1,7 +1,7 @@
 # Suggest using `toStrictEqual()` (`prefer-strict-equal`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 💡 This rule provides
diff --git a/docs/rules/prefer-to-be.md b/docs/rules/prefer-to-be.md
index 58d012df0..60d0e8e40 100644
--- a/docs/rules/prefer-to-be.md
+++ b/docs/rules/prefer-to-be.md
@@ -1,7 +1,7 @@
 # Suggest using `toBe()` for primitive literals (`prefer-to-be`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `style`.
 
 🔧 This rule is automatically fixable using the `--fix`
diff --git a/docs/rules/prefer-to-contain.md b/docs/rules/prefer-to-contain.md
index a4116b8e1..d6b4600a4 100644
--- a/docs/rules/prefer-to-contain.md
+++ b/docs/rules/prefer-to-contain.md
@@ -1,7 +1,7 @@
 # Suggest using `toContain()` (`prefer-to-contain`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `style`.
 
 🔧 This rule is automatically fixable using the `--fix`
diff --git a/docs/rules/prefer-to-have-length.md b/docs/rules/prefer-to-have-length.md
index d167eb9d2..38d965838 100644
--- a/docs/rules/prefer-to-have-length.md
+++ b/docs/rules/prefer-to-have-length.md
@@ -1,7 +1,7 @@
 # Suggest using `toHaveLength()` (`prefer-to-have-length`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `style`.
 
 🔧 This rule is automatically fixable using the `--fix`
diff --git a/docs/rules/prefer-todo.md b/docs/rules/prefer-todo.md
index 5361b3513..104ca69fc 100644
--- a/docs/rules/prefer-todo.md
+++ b/docs/rules/prefer-todo.md
@@ -1,7 +1,7 @@
 # Suggest using `test.todo` (`prefer-todo`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 🔧 This rule is automatically fixable using the `--fix`
diff --git a/docs/rules/require-hook.md b/docs/rules/require-hook.md
index e59ba1da2..a8e6fc6d4 100644
--- a/docs/rules/require-hook.md
+++ b/docs/rules/require-hook.md
@@ -1,7 +1,7 @@
 # Require setup and teardown code to be within a hook (`require-hook`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/require-to-throw-message.md b/docs/rules/require-to-throw-message.md
index 9e89f53d7..afb529cc0 100644
--- a/docs/rules/require-to-throw-message.md
+++ b/docs/rules/require-to-throw-message.md
@@ -1,7 +1,7 @@
 # Require a message for `toThrow()` (`require-to-throw-message`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/require-top-level-describe.md b/docs/rules/require-top-level-describe.md
index 1242f38d3..8e99f5337 100644
--- a/docs/rules/require-top-level-describe.md
+++ b/docs/rules/require-top-level-describe.md
@@ -1,7 +1,7 @@
 # Require test cases and hooks to be inside a `describe` block (`require-top-level-describe`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/unbound-method.md b/docs/rules/unbound-method.md
index 3b282625f..1fbbf53fb 100644
--- a/docs/rules/unbound-method.md
+++ b/docs/rules/unbound-method.md
@@ -1,7 +1,7 @@
 # Enforce unbound methods are called with their expected scope (`unbound-method`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`.
 
 <!-- end rule header -->
diff --git a/docs/rules/valid-describe-callback.md b/docs/rules/valid-describe-callback.md
index 55e34a402..920e46c0c 100644
--- a/docs/rules/valid-describe-callback.md
+++ b/docs/rules/valid-describe-callback.md
@@ -1,7 +1,7 @@
 # Enforce valid `describe()` callback (`valid-describe-callback`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `recommended`.
 
 <!-- end rule header -->
diff --git a/docs/rules/valid-expect-in-promise.md b/docs/rules/valid-expect-in-promise.md
index bb8fc9bc9..d8a1cbaab 100644
--- a/docs/rules/valid-expect-in-promise.md
+++ b/docs/rules/valid-expect-in-promise.md
@@ -1,7 +1,7 @@
 # Ensure promises that have expectations in their chain are valid (`valid-expect-in-promise`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `recommended`.
 
 <!-- end rule header -->
diff --git a/docs/rules/valid-expect.md b/docs/rules/valid-expect.md
index dee32269c..09d41318f 100644
--- a/docs/rules/valid-expect.md
+++ b/docs/rules/valid-expect.md
@@ -1,7 +1,7 @@
 # Enforce valid `expect()` usage (`valid-expect`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
 `all`, `recommended`.
 
 <!-- end rule header -->
diff --git a/docs/rules/valid-title.md b/docs/rules/valid-title.md
index 1e7e15c93..87c1993f0 100644
--- a/docs/rules/valid-title.md
+++ b/docs/rules/valid-title.md
@@ -1,7 +1,7 @@
 # Enforce valid titles (`valid-title`)
 
 💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):
+[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`
diff --git a/tools/rule-notices.ts b/tools/rule-notices.ts
index 3762c70de..19a47bc8c 100644
--- a/tools/rule-notices.ts
+++ b/tools/rule-notices.ts
@@ -9,7 +9,7 @@ enum MESSAGE_TYPE {
 
 export const MESSAGES = {
   [MESSAGE_TYPE.CONFIGS]:
-    '💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations):',
+    '💼 This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):',
   [MESSAGE_TYPE.DEPRECATED]: '❌ This rule is deprecated.',
   [MESSAGE_TYPE.FIXABLE]:
     '🔧 This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.',

From e1105cce860f533ce7c4007633764f4902dad655 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Wed, 7 Sep 2022 11:30:05 -0400
Subject: [PATCH 20/23] test: ensure rule docs mention named options

---
 docs/rules/unbound-method.md |  3 ++-
 tools/regenerate-docs.ts     | 48 +++++++++++++++++++++++++++++++-----
 2 files changed, 44 insertions(+), 7 deletions(-)

diff --git a/docs/rules/unbound-method.md b/docs/rules/unbound-method.md
index 1fbbf53fb..95998e8cc 100644
--- a/docs/rules/unbound-method.md
+++ b/docs/rules/unbound-method.md
@@ -52,7 +52,8 @@ which should be applied to the rest of your codebase.
 
 ## Options
 
-See [`@typescript-eslint/unbound-method`][original-rule] options.
+See [`@typescript-eslint/unbound-method`][original-rule] options (e.g.
+`ignoreStatic`).
 
 <sup>Taken with ❤️ [from `@typescript-eslint` core][original-rule]</sup>
 
diff --git a/tools/regenerate-docs.ts b/tools/regenerate-docs.ts
index 6b8fa8cea..e2385ce3d 100644
--- a/tools/regenerate-docs.ts
+++ b/tools/regenerate-docs.ts
@@ -2,7 +2,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import { TSESLint } from '@typescript-eslint/utils';
+import { JSONSchema, TSESLint } from '@typescript-eslint/utils';
 import prettier, { Options } from 'prettier';
 import { prettier as prettierRC } from '../package.json';
 import plugin from '../src/index';
@@ -156,6 +156,40 @@ const expectContent = (
   }
 };
 
+/**
+ * Gather a list of named options from a rule schema.
+ * @param jsonSchema - the JSON schema to check
+ * @returns - list of named options we could detect from the schema
+ */
+const getAllNamedOptions = (jsonSchema: JSONSchema.JSONSchema4): string[] => {
+  if (!jsonSchema) {
+    return [];
+  }
+
+  if (Array.isArray(jsonSchema)) {
+    return jsonSchema.flatMap(getAllNamedOptions);
+  }
+
+  if (jsonSchema.items) {
+    return getAllNamedOptions(jsonSchema.items);
+  }
+
+  if (jsonSchema.properties) {
+    return Object.keys(jsonSchema.properties);
+  }
+
+  return [];
+};
+
+/**
+ * Check if a rule schema is non-blank/empty and thus has actual options.
+ * @param jsonSchema - the JSON schema to check
+ * @returns - whether the schema has options
+ */
+const hasOptions = (jsonSchema: JSONSchema.JSONSchema4): boolean =>
+  (Array.isArray(jsonSchema) && jsonSchema.length > 0) ||
+  (typeof jsonSchema === 'object' && Object.keys(jsonSchema).length > 0);
+
 // copied from https://github.com/babel/babel/blob/d8da63c929f2d28c401571e2a43166678c555bc4/packages/babel-helpers/src/helpers.js#L602-L606
 /* istanbul ignore next */
 const interopRequireDefault = (obj: any): { default: any } =>
@@ -203,12 +237,14 @@ details.forEach(({ name, description, schema }) => {
 
   // Check for potential issues with the rule doc.
 
-  const hasOptions =
-    (Array.isArray(schema) && schema.length > 0) ||
-    (typeof schema === 'object' && Object.keys(schema).length > 0);
-
+  // "Rule details" section.
   expectContent(name, contents, '## Rule details', true);
-  expectContent(name, contents, '## Options', hasOptions);
+
+  // "Options" section.
+  expectContent(name, contents, '## Options', hasOptions(schema));
+  for (const namedOption of getAllNamedOptions(schema)) {
+    expectContent(name, contents, namedOption, true); // Each rule option is mentioned.
+  }
 });
 
 const [baseRules, typeRules] = details.reduce<[RuleDetails[], RuleDetails[]]>(

From 34e692ac041243ab6d6daf4853cb0e2b1b965266 Mon Sep 17 00:00:00 2001
From: Simen Bekkhus <sbekkhus91@gmail.com>
Date: Sat, 10 Sep 2022 01:03:58 +0200
Subject: [PATCH 21/23] Update tools/regenerate-docs.ts

Co-authored-by: Gareth Jones <Jones258@Gmail.com>
---
 tools/regenerate-docs.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/regenerate-docs.ts b/tools/regenerate-docs.ts
index e2385ce3d..81e023efb 100644
--- a/tools/regenerate-docs.ts
+++ b/tools/regenerate-docs.ts
@@ -28,7 +28,7 @@ interface RuleDetails {
   fixable: FixType | false;
   requiresTypeChecking: boolean;
   deprecated: boolean;
-  schema: any;
+  schema: JSONSchema.JSONSchema4;
 }
 
 type RuleModule = TSESLint.RuleModule<string, unknown[]> & {

From de63782e13cb20a0331bfff605c39155c35aeb63 Mon Sep 17 00:00:00 2001
From: Simen Bekkhus <sbekkhus91@gmail.com>
Date: Sat, 10 Sep 2022 13:21:02 +0200
Subject: [PATCH 22/23] Apply suggestions from code review

---
 tools/rule-notices.ts | 2 --
 1 file changed, 2 deletions(-)

diff --git a/tools/rule-notices.ts b/tools/rule-notices.ts
index 19a47bc8c..d73a09605 100644
--- a/tools/rule-notices.ts
+++ b/tools/rule-notices.ts
@@ -29,8 +29,6 @@ function getConfigsForRule(ruleName: string) {
 
   for (configName in configs) {
     const config = configs[configName];
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- we don't have a static type for rule names
-    // @ts-ignore
     const value = config.rules[`jest/${ruleName}`];
     const isEnabled = [2, 'error'].includes(value);
 

From e96211a50a33f14a668f24276be427ec4a96becc Mon Sep 17 00:00:00 2001
From: semantic-release-bot <semantic-release-bot@martynus.net>
Date: Fri, 9 Sep 2022 23:08:08 +0000
Subject: [PATCH 23/23] chore(release): 27.0.3 [skip ci]

## [27.0.3](https://github.com/jest-community/eslint-plugin-jest/compare/v27.0.2...v27.0.3) (2022-09-09)

### Bug Fixes

* ensure jest globals are enabled in `styles` config ([#1241](https://github.com/jest-community/eslint-plugin-jest/issues/1241)) ([a165e98](https://github.com/jest-community/eslint-plugin-jest/commit/a165e98b2a8728c427d6c484122dc9e64629052b))
---
 CHANGELOG.md | 7 +++++++
 package.json | 2 +-
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4714130c7..cd791f06f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,10 @@
+## [27.0.3](https://github.com/jest-community/eslint-plugin-jest/compare/v27.0.2...v27.0.3) (2022-09-09)
+
+
+### Bug Fixes
+
+* ensure jest globals are enabled in `styles` config ([#1241](https://github.com/jest-community/eslint-plugin-jest/issues/1241)) ([a165e98](https://github.com/jest-community/eslint-plugin-jest/commit/a165e98b2a8728c427d6c484122dc9e64629052b))
+
 ## [27.0.2](https://github.com/jest-community/eslint-plugin-jest/compare/v27.0.1...v27.0.2) (2022-09-08)
 
 
diff --git a/package.json b/package.json
index 1de966add..3433ad32d 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-jest",
-  "version": "27.0.2",
+  "version": "27.0.3",
   "description": "ESLint rules for Jest",
   "keywords": [
     "eslint",