docs: automate docs with eslint-doc-generator (#690)

bmish · web-flow · commit a09b36158ce7 · 2022-11-20T11:26:54.000+01:00
diff --git a/README.md b/README.md
diff --git a/docs/rules/await-async-query.md b/docs/rules/await-async-query.md
@@ -1,5 +1,9 @@
 # Enforce promises from async queries to be handled (`testing-library/await-async-query`)
 
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
+
 Ensure that promises returned by async queries are handled properly.
 
 ## Rule Details
diff --git a/docs/rules/await-async-utils.md b/docs/rules/await-async-utils.md
@@ -1,4 +1,8 @@
-# Enforce promises from async utils to be handled (`testing-library/await-async-utils`)
+# Enforce promises from async utils to be awaited properly (`testing-library/await-async-utils`)
+
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
 
 Ensure that promises returned by async utils are handled properly.
 
diff --git a/docs/rules/await-fire-event.md b/docs/rules/await-fire-event.md
@@ -1,4 +1,8 @@
-# Enforce promises from fire event methods to be handled (`testing-library/await-fire-event`)
+# Enforce promises from `fireEvent` methods to be handled (`testing-library/await-fire-event`)
+
+💼 This rule is enabled in the following configs: `marko`, `vue`.
+
+<!-- end auto-generated rule header -->
 
 Ensure that promises returned by `fireEvent` methods are handled
 properly.
diff --git a/docs/rules/consistent-data-testid.md b/docs/rules/consistent-data-testid.md
@@ -1,4 +1,6 @@
-# Enforces consistent naming for the data-testid attribute (`testing-library/consistent-data-testid`)
+# Ensures consistent usage of `data-testid` (`testing-library/consistent-data-testid`)
+
+<!-- end auto-generated rule header -->
 
 Ensure `data-testid` values match a provided regex. This rule is un-opinionated, and requires configuration.
 
diff --git a/docs/rules/no-await-sync-events.md b/docs/rules/no-await-sync-events.md
@@ -1,5 +1,7 @@
 # Disallow unnecessary `await` for sync events (`testing-library/no-await-sync-events`)
 
+<!-- end auto-generated rule header -->
+
 Ensure that sync simulated events are not awaited unnecessarily.
 
 ## Rule Details
diff --git a/docs/rules/no-await-sync-query.md b/docs/rules/no-await-sync-query.md
@@ -1,5 +1,9 @@
 # Disallow unnecessary `await` for sync queries (`testing-library/no-await-sync-query`)
 
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
+
 Ensure that sync queries are not awaited unnecessarily.
 
 ## Rule Details
diff --git a/docs/rules/no-container.md b/docs/rules/no-container.md
@@ -1,5 +1,9 @@
 # Disallow the use of `container` methods (`testing-library/no-container`)
 
+💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
+
 By using `container` methods like `.querySelector` you may lose a lot of the confidence that the user can really interact with your UI. Also, the test becomes harder to read, and it will break more frequently.
 
 This applies to Testing Library frameworks built on top of **DOM Testing Library**
diff --git a/docs/rules/no-debugging-utils.md b/docs/rules/no-debugging-utils.md
@@ -1,4 +1,8 @@
-# Disallow the use of debugging utilities (`testing-library/no-debugging-utils`)
+# Disallow the use of debugging utilities like `debug` (`testing-library/no-debugging-utils`)
+
+💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
 
 Just like `console.log` statements pollutes the browser's output, debug statements also pollutes the tests if one of your teammates forgot to remove it. `debug` statements should be used when you actually want to debug your tests but should not be pushed to the codebase.
 
@@ -37,6 +41,8 @@ const { screen } = require('@testing-library/react');
 screen.debug();
 ```
 
+## Options
+
 You can control which debugging utils are checked for with the `utilsToCheckFor` option:
 
 ```json
diff --git a/docs/rules/no-dom-import.md b/docs/rules/no-dom-import.md
@@ -1,5 +1,11 @@
 # Disallow importing from DOM Testing Library (`testing-library/no-dom-import`)
 
+💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
 Ensure that there are no direct imports from `@testing-library/dom` or
 `dom-testing-library` when using some testing library framework
 wrapper.
diff --git a/docs/rules/no-global-regexp-flag-in-query.md b/docs/rules/no-global-regexp-flag-in-query.md
@@ -1,5 +1,9 @@
 # Disallow the use of the global RegExp flag (/g) in queries (`testing-library/no-global-regexp-flag-in-query`)
 
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
 Ensure that there are no global RegExp flags used when using queries.
 
 ## Rule Details
diff --git a/docs/rules/no-manual-cleanup.md b/docs/rules/no-manual-cleanup.md
@@ -1,5 +1,7 @@
 # Disallow the use of `cleanup` (`testing-library/no-manual-cleanup`)
 
+<!-- end auto-generated rule header -->
+
 `cleanup` is performed automatically if the testing framework you're using supports the `afterEach` global (like mocha, Jest, and Jasmine). In this case, it's unnecessary to do manual cleanups after each test unless you skip the auto-cleanup with environment variables such as `RTL_SKIP_AUTO_CLEANUP` for React.
 
 ## Rule Details
diff --git a/docs/rules/no-node-access.md b/docs/rules/no-node-access.md
@@ -1,5 +1,9 @@
 # Disallow direct Node access (`testing-library/no-node-access`)
 
+💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
+
 The Testing Library already provides methods for querying DOM elements.
 
 ## Rule Details
diff --git a/docs/rules/no-promise-in-fire-event.md b/docs/rules/no-promise-in-fire-event.md
@@ -1,5 +1,9 @@
 # Disallow the use of promises passed to a `fireEvent` method (`testing-library/no-promise-in-fire-event`)
 
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
+
 Methods from `fireEvent` expect to receive a DOM element. Passing a promise will end up in an error, so it must be prevented.
 
 Examples of **incorrect** code for this rule:
diff --git a/docs/rules/no-render-in-setup.md b/docs/rules/no-render-in-setup.md
@@ -1,4 +1,8 @@
-# Disallow the use of `render` in setup functions (`testing-library/no-render-in-setup`)
+# Disallow the use of `render` in testing frameworks setup functions (`testing-library/no-render-in-setup`)
+
+💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
 
 ## Rule Details
 
@@ -74,6 +78,8 @@ it('Should have foo and bar', () => {
 });
 ```
 
+## Options
+
 If you would like to allow the use of `render` (or a custom render function) in _either_ `beforeAll` or `beforeEach`, this can be configured using the option `allowTestingFrameworkSetupHook`. This may be useful if you have configured your tests to [skip auto cleanup](https://testing-library.com/docs/react-testing-library/setup#skipping-auto-cleanup). `allowTestingFrameworkSetupHook` is an enum that accepts either `"beforeAll"` or `"beforeEach"`.
 
 ```
diff --git a/docs/rules/no-unnecessary-act.md b/docs/rules/no-unnecessary-act.md
@@ -1,5 +1,9 @@
 # Disallow wrapping Testing Library utils or empty callbacks in `act` (`testing-library/no-unnecessary-act`)
 
+💼 This rule is enabled in the following configs: `marko`, `react`.
+
+<!-- end auto-generated rule header -->
+
 > ⚠️ The `act` method is only available on the following Testing Library packages:
 >
 > - `@testing-library/react` (supported by this plugin)
diff --git a/docs/rules/no-wait-for-empty-callback.md b/docs/rules/no-wait-for-empty-callback.md
@@ -1,4 +1,8 @@
-# Empty callbacks inside `waitFor` and `waitForElementToBeRemoved` are not preferred (`testing-library/no-wait-for-empty-callback`)
+# Disallow empty callbacks for `waitFor` and `waitForElementToBeRemoved` (`testing-library/no-wait-for-empty-callback`)
+
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
 
 ## Rule Details
 
diff --git a/docs/rules/no-wait-for-multiple-assertions.md b/docs/rules/no-wait-for-multiple-assertions.md
@@ -1,4 +1,8 @@
-# Disallow the use of multiple expect inside `waitFor` (`testing-library/no-wait-for-multiple-assertions`)
+# Disallow the use of multiple `expect` calls inside `waitFor` (`testing-library/no-wait-for-multiple-assertions`)
+
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
 
 ## Rule Details
 
diff --git a/docs/rules/no-wait-for-side-effects.md b/docs/rules/no-wait-for-side-effects.md
@@ -1,4 +1,8 @@
-# Disallow the use of side effects inside `waitFor` (`testing-library/no-wait-for-side-effects`)
+# Disallow the use of side effects in `waitFor` (`testing-library/no-wait-for-side-effects`)
+
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
 
 ## Rule Details
 
diff --git a/docs/rules/no-wait-for-snapshot.md b/docs/rules/no-wait-for-snapshot.md
@@ -1,4 +1,8 @@
-# Ensures no snapshot is generated inside a `waitFor` call (`testing-library/no-wait-for-snapshot`)
+# Ensures no snapshot is generated inside of a `waitFor` call (`testing-library/no-wait-for-snapshot`)
+
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
 
 Ensure that no calls to `toMatchSnapshot` or `toMatchInlineSnapshot` are made from within a `waitFor` method (or any of the other async utility methods).
 
diff --git a/docs/rules/prefer-explicit-assert.md b/docs/rules/prefer-explicit-assert.md
@@ -1,4 +1,6 @@
-# Suggest using explicit assertions rather than just `getBy*` queries (`testing-library/prefer-explicit-assert`)
+# Suggest using explicit assertions rather than standalone queries (`testing-library/prefer-explicit-assert`)
+
+<!-- end auto-generated rule header -->
 
 Testing Library `getBy*` queries throw an error if the element is not
 found. Some users like this behavior to use the query itself as an
diff --git a/docs/rules/prefer-find-by.md b/docs/rules/prefer-find-by.md
@@ -1,4 +1,10 @@
-# Suggest using `findBy*` methods instead of the `waitFor` + `getBy` queries (`testing-library/prefer-find-by`)
+# Suggest using `find(All)By*` query instead of `waitFor` + `get(All)By*` to wait for elements (`testing-library/prefer-find-by`)
+
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
 
 `findBy*` queries are a simple combination of `getBy*` queries and `waitFor`. The `findBy*` queries accept the `waitFor` options as the last argument. (i.e. `screen.findByText('text', queryOptions, waitForOptions)`)
 
diff --git a/docs/rules/prefer-presence-queries.md b/docs/rules/prefer-presence-queries.md
@@ -1,4 +1,8 @@
-# Enforce specific queries when checking element is present or not (`testing-library/prefer-presence-queries`)
+# Ensure appropriate `get*`/`query*` queries are used with their respective matchers (`testing-library/prefer-presence-queries`)
+
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
 
 The (DOM) Testing Library allows to query DOM elements using different types of queries such as `get*` and `query*`. Using `get*` throws an error in case the element is not found, while `query*` returns null instead of throwing (or empty array for `queryAllBy*` ones). These differences are useful in some situations:
 
diff --git a/docs/rules/prefer-query-by-disappearance.md b/docs/rules/prefer-query-by-disappearance.md
@@ -1,5 +1,9 @@
 # Suggest using `queryBy*` queries when waiting for disappearance (`testing-library/prefer-query-by-disappearance`)
 
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
+
 ## Rule Details
 
 This rule enforces using `queryBy*` queries when waiting for disappearance with `waitForElementToBeRemoved`.
diff --git a/docs/rules/prefer-screen-queries.md b/docs/rules/prefer-screen-queries.md
@@ -1,5 +1,9 @@
 # Suggest using `screen` while querying (`testing-library/prefer-screen-queries`)
 
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
+
 ## Rule Details
 
 DOM Testing Library (and other Testing Library frameworks built on top of it) exports a `screen` object which has every query (and a `debug` method). This works better with autocomplete and makes each test a little simpler to write and maintain.
diff --git a/docs/rules/prefer-user-event.md b/docs/rules/prefer-user-event.md
@@ -1,4 +1,6 @@
-# Suggest using `userEvent` library instead of `fireEvent` for simulating user interaction (`testing-library/prefer-user-event`)
+# Suggest using `userEvent` over `fireEvent` for simulating user interactions (`testing-library/prefer-user-event`)
+
+<!-- end auto-generated rule header -->
 
 From
 [testing-library/dom-testing-library#107](https://github.com/testing-library/dom-testing-library/issues/107):
diff --git a/docs/rules/prefer-wait-for.md b/docs/rules/prefer-wait-for.md
@@ -1,5 +1,9 @@
 # Use `waitFor` instead of deprecated wait methods (`testing-library/prefer-wait-for`)
 
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
 `dom-testing-library` v7 released a new async util called `waitFor` which satisfies the use cases of `wait`, `waitForElement`, and `waitForDomChange` making them deprecated.
 
 ## Rule Details
diff --git a/docs/rules/render-result-naming-convention.md b/docs/rules/render-result-naming-convention.md
@@ -1,5 +1,9 @@
 # Enforce a valid naming for return value from `render` (`testing-library/render-result-naming-convention`)
 
+💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
+
+<!-- end auto-generated rule header -->
+
 > The name `wrapper` is old cruft from `enzyme` and we don't need that here. The return value from `render` is not "wrapping" anything. It's simply a collection of utilities that you should actually not often need anyway.
 
 ## Rule Details
diff --git a/package.json b/package.json
@@ -30,10 +30,13 @@
 		"postbuild": "cpy README.md ./dist && cpy package.json ./dist && cpy LICENSE ./dist",
 		"format": "prettier --write .",
 		"format:check": "prettier --check .",
-		"generate:configs": "ts-node tools/generate-configs",
-		"generate:rules-list": "ts-node tools/generate-rules-list",
-		"lint": "eslint . --max-warnings 0 --ext .js,.ts",
-		"lint:fix": "npm run lint -- --fix",
+		"generate": "npm-run-all \"generate:*\"",
+		"generate:configs": "ts-node tools/generate-configs && npm run format",
+		"generate:rules-list": "npm run build && eslint-doc-generator --path-rule-list \"../README.md\" --path-rule-doc \"../docs/rules/{name}.md\" dist/ && npm run format",
+		"lint": "npm-run-all \"lint:*\"",
+		"lint:generate": "npm run generate && git diff --exit-code",
+		"lint:js": "eslint . --max-warnings 0 --ext .js,.ts",
+		"lint:js:fix": "npm run lint:js -- --fix",
 		"prepare": "is-ci || husky install",
 		"semantic-release": "semantic-release",
 		"test": "jest",
@@ -59,6 +62,7 @@
 		"eslint": "^8.28.0",
 		"eslint-config-kentcdodds": "^20.4.0",
 		"eslint-config-prettier": "^8.5.0",
+		"eslint-doc-generator": "^0.24.0",
 		"eslint-plugin-import": "^2.26.0",
 		"eslint-plugin-jest": "^27.1.5",
 		"eslint-plugin-jest-formatting": "^3.1.0",
@@ -71,6 +75,7 @@
 		"is-ci": "^3.0.1",
 		"jest": "^28.1.3",
 		"lint-staged": "^13.0.3",
+		"npm-run-all": "^4.1.5",
 		"prettier": "2.7.1",
 		"semantic-release": "^19.0.5",
 		"ts-jest": "^28.0.8",
diff --git a/tools/generate-rules-list/index.ts b/tools/generate-rules-list/index.ts
diff --git a/tools/generate-rules-list/utils.ts b/tools/generate-rules-list/utils.ts
