docs: auto-generate rule docs (#1)

JasonWeinzierl · web-flow · commit 10674fe8f86d · 2025-01-29T10:50:49.000-06:00
- Added eslint-doc-generator
- Added markdownlint
- Re-created rule headers and README rules list
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -0,0 +1,6 @@
+{
+  "line-length": false,
+  "MD024": {
+    "siblings_only": true
+  }
+}
diff --git a/README.md b/README.md
@@ -12,6 +12,9 @@ There is no recommended configuration for this package, as all of the rules are
 This project is a fork of [`eslint-plugin-rxjs-angular`](https://github.com/cartant/eslint-plugin-rxjs-angular)
 initially started to support the new ESLint flat config format.
 
+- The old `.eslintrc` format is not supported.
+  - If you need to continue using this old format, use the original `eslint-plugin-rxjs` or a different fork.
+
 A complete description of all changes are documented in the [CHANGELOG](CHANGELOG.md) file.
 
 ## Install
@@ -51,8 +54,14 @@ See [Linting with Type Information](https://typescript-eslint.io/getting-started
 
 The package includes the following rules:
 
-| Rule | Description | Recommended |
-| --- | --- | --- |
-| [`prefer-async-pipe`](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-angular-x/blob/main/docs/rules/prefer-async-pipe.md) | Forbids the calling of `subscribe` within Angular components. | No |
-| [`prefer-composition`](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-angular-x/blob/main/docs/rules/prefer-composition.md) | Forbids `subscribe` calls that are not composed within Angular components (and, optionally, within services, directives, and pipes). | No |
-| [`prefer-takeuntil`](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-angular-x/blob/main/docs/rules/prefer-takeuntil.md) | Forbids Calling `subscribe` without an accompanying `takeUntil`. | No |
+<!-- begin auto-generated rules list -->
+
+💭 Requires [type information](https://typescript-eslint.io/linting/typed-linting).
+
+| Name                                                   | Description                                                                                                                                         | 💭 |
+| :----------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :- |
+| [prefer-async-pipe](docs/rules/prefer-async-pipe.md)   | Disallow the calling of `subscribe` within Angular components.                                                                                      | 💭 |
+| [prefer-composition](docs/rules/prefer-composition.md) | Disallow `subscribe` calls that are not composed within Angular components (and, optionally, within services, directives, and pipes).               | 💭 |
+| [prefer-takeuntil](docs/rules/prefer-takeuntil.md)     | Disallow `subscribe` calls without an accompanying `takeUntil` within Angular components (and, optionally, within services, directives, and pipes). | 💭 |
+
+<!-- end auto-generated rules list -->
diff --git a/docs/rules/prefer-async-pipe.md b/docs/rules/prefer-async-pipe.md
@@ -1,10 +1,10 @@
-# Use container components and async pipe (`prefer-async-pipe`)
+# Disallow the calling of `subscribe` within Angular components (`rxjs-angular-x/prefer-async-pipe`)
 
-This rule effects failures if explicit calls to `subscribe` are made within a component. Instead, use a child component to which a value is passed by using the async pipe in the parent component's template.
+💭 This rule requires [type information](https://typescript-eslint.io/linting/typed-linting).
 
-## Options
+<!-- end auto-generated rule header -->
 
-This rule has no options.
+This rule effects failures if explicit calls to `subscribe` are made within a component. Instead, use a child component to which a value is passed by using the async pipe in the parent component's template.
 
 ## Further reading
 
diff --git a/docs/rules/prefer-composition.md b/docs/rules/prefer-composition.md
@@ -1,4 +1,8 @@
-# Use subscription composition (`prefer-composition`)
+# Disallow `subscribe` calls that are not composed within Angular components (and, optionally, within services, directives, and pipes) (`rxjs-angular-x/prefer-composition`)
+
+💭 This rule requires [type information](https://typescript-eslint.io/linting/typed-linting).
+
+<!-- end auto-generated rule header -->
 
 This rule effects failures if `subscribe` calls are made with a component and the returned subscription is not composed into a subscription that is unsubscribed when the component is destroyed.
 
@@ -48,6 +52,14 @@ export class SomeComponent implements OnInit, OnDestroy {
 
 ## Options
 
+<!-- begin auto-generated rule options list -->
+
+| Name              | Description                                    | Type     |
+| :---------------- | :--------------------------------------------- | :------- |
+| `checkDecorators` | An optional array of decorator names to check. | String[] |
+
+<!-- end auto-generated rule options list -->
+
 This rule accepts a single option which is an object with a `checkDecorators` property which is an array containing the names of the decorators that determine whether or not a class is checked. By default, `checkDecorators` is `["Component"]`.
 
 ```json
@@ -61,4 +73,4 @@ This rule accepts a single option which is an object with a `checkDecorators` pr
 
 ## Further reading
 
-- [Composing Subscriptions](https://ncjamieson.com/composing-subscriptions/)
+- [Composing Subscriptions](https://ncjamieson.com/composing-subscriptions/)
diff --git a/docs/rules/prefer-takeuntil.md b/docs/rules/prefer-takeuntil.md
@@ -1,4 +1,8 @@
-# Use `takeUntil` and  `ngOnDestroy` (`prefer-takeuntil`)
+# Disallow `subscribe` calls without an accompanying `takeUntil` within Angular components (and, optionally, within services, directives, and pipes) (`rxjs-angular-x/prefer-takeuntil`)
+
+💭 This rule requires [type information](https://typescript-eslint.io/linting/typed-linting).
+
+<!-- end auto-generated rule header -->
 
 This rule effects failures if `subscribe` is called within a component and the `takeUntil`-destroyed pattern is not used.
 
@@ -50,6 +54,17 @@ class SomeComponent implements OnDestroy, OnInit {
 
 ## Options
 
+<!-- begin auto-generated rule options list -->
+
+| Name              | Description                                                     | Type     |
+| :---------------- | :-------------------------------------------------------------- | :------- |
+| `alias`           | An optional array of operator names that alias for `takeUntil`. | String[] |
+| `checkComplete`   | Check for `complete` calls.                                     | Boolean  |
+| `checkDecorators` | An optional array of decorator names to check.                  | String[] |
+| `checkDestroy`    | Check for `Subject`-based `ngOnDestroy`.                        | Boolean  |
+
+<!-- end auto-generated rule options list -->
+
 This rule accepts a single option which is an object with `checkComplete`, `checkDecorators`, `checkDestroy` and `alias` properties.
 
 The `checkComplete` property is a boolean that determines whether or not `complete` must be called after `next` and the `checkDestroy` property is a boolean that determines whether or not a `Subject`-based `ngOnDestroy` must be implemented.
@@ -74,4 +89,4 @@ The `alias` property is an array of names of operators that should be treated si
 
 ## Further reading
 
-- [Avoiding takeUntil leaks](https://ncjamieson.com/avoiding-takeuntil-leaks/)
+- [Avoiding takeUntil leaks](https://ncjamieson.com/avoiding-takeuntil-leaks/)
diff --git a/package.json b/package.json
@@ -43,8 +43,11 @@
   ],
   "scripts": {
     "build": "tsup",
-    "lint": "yarn lint-js",
+    "lint": "yarn lint-js && yarn lint-docs && yarn lint-eslint-docs",
     "lint-js": "eslint",
+    "lint-docs": "markdownlint-cli2 \"**/*.md\" \"#node_modules\"",
+    "lint-eslint-docs": "yarn build && eslint-doc-generator --check",
+    "docs": "eslint-doc-generator",
     "release": "bumpp && echo \"Create a new release in GitHub to trigger the publish workflow.\"",
     "test": "vitest",
     "coverage": "vitest run --coverage",
@@ -53,6 +56,7 @@
   "dependencies": {
     "@typescript-eslint/utils": "^8.19.1",
     "common-tags": "^1.8.0",
+    "markdownlint-cli2": "^0.17.2",
     "ts-api-utils": "^2.0.0",
     "tslib": "^2.1.0"
   },
@@ -77,6 +81,7 @@
     "bumpp": "^10.0.1",
     "eslint": "^9.19.0",
     "eslint-config-flat-gitignore": "^1.0.0",
+    "eslint-doc-generator": "^2.0.2",
     "eslint-import-resolver-typescript": "^3.7.0",
     "eslint-plugin-eslint-plugin": "^6.4.0",
     "eslint-plugin-import-x": "^4.6.1",
diff --git a/yarn.lock b/yarn.lock
