chore(website): generate rule docs options automatically (#5386)

* chore(website): generate rule docs options automatically * Apply suggestions from code review Co-authored-by: Joshua Chen <[email protected]> * First round of changes * Simplify Prettier types * Progress on using defs * Progress, through the letter 'd' for rules * Through explicit-module-boundary-types * rip, ban-types defaults * Cleaner separation for adding headers * ...I meant headings * Finished specifically base rule extensions * Fix unit test, and enable debug cypress logging * Fix deprecation notices, and ci.yml env indent * Fix up lang and <sup> * No, not sup * Removed bunch more options docs cruft * naming-convention, I give up * Aha, a missing lint rule * member-ordering, I give up on you too * Several more docs automations * Fixed options index * Also above Related To * Aha, jsx working * Thanks lint - correct no-inferrable-types headings * Update packages/eslint-plugin/src/rules/no-implicit-any-catch.ts Co-authored-by: Brad Zacher <[email protected]> * Fix explicit-function-return-type Co-authored-by: Joshua Chen <[email protected]> Co-authored-by: Brad Zacher <[email protected]>
typescript-eslint · Aug 17, 2022 · 81f3ffc · 81f3ffc
1 parent ff573d9
commit 81f3ffc
Show file tree

Hide file tree

Showing 150 changed files with 882 additions and 2,259 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -188,7 +188,9 @@ jobs:
       - name: Install Cypress
         run: yarn cypress install
 
-      - name: Cypress run
+      - env:
+          DEBUG: '@cypress/github-action'
+        name: Cypress run
         uses: cypress-io/github-action@v2
         with:
           project: ./packages/website

diff --git a/packages/eslint-plugin/docs/rules/TEMPLATE.md b/packages/eslint-plugin/docs/rules/TEMPLATE.md
@@ -20,33 +20,6 @@ To fill out: tell us more about this rule.
 // To fill out: correct code
 ```
 
-## Options
-
-This rule is not configurable.
-
-```jsonc
-// .eslintrc.json
-{
-  "rules": {
-    "@typescript-eslint/your-rule-name": "error"
-  }
-}
-```
-
-If not configurable: This rule is not configurable.
-
-If configurable...
-
-```ts
-type Options = {
-  someOption?: boolean;
-};
-
-const defaultOptions: Options = {
-  someOption: false,
-};
-```
-
 ## When Not To Use It
 
 To fill out: why wouldn't you want to use this rule?

diff --git a/packages/eslint-plugin/docs/rules/adjacent-overload-signatures.md b/packages/eslint-plugin/docs/rules/adjacent-overload-signatures.md
@@ -88,19 +88,6 @@ export function foo(n: number): void;
 export function foo(sn: string | number): void;
 ```
 
-## Options
-
-```jsonc
-// .eslintrc.json
-{
-  "rules": {
-    "@typescript-eslint/adjacent-overload-signatures": "error"
-  }
-}
-```
-
-This rule is not configurable.
-
 ## When Not To Use It
 
 If you don't care about the general structure of the code, then you will not need this rule.
diff --git a/packages/eslint-plugin/docs/rules/array-type.md b/packages/eslint-plugin/docs/rules/array-type.md
@@ -14,25 +14,6 @@ This rule aims to standardize usage of array types within your codebase.
 
 ## Options
 
-```ts
-type ArrayOption = 'array' | 'generic' | 'array-simple';
-type Options = {
-  default: ArrayOption;
-  readonly?: ArrayOption;
-};
-
-const defaultOptions: Options = {
-  default: 'array',
-};
-```
-
-The rule accepts an options object with the following properties:
-
-- `default` - sets the array type expected for mutable cases.
-- `readonly` - sets the array type expected for readonly arrays. If this is omitted, then the value for `default` will be used.
-
-Each property can be set to one of three strings: `'array' | 'generic' | 'array-simple'`.
-
 The default config will enforce that all mutable and readonly arrays use the `'array'` syntax.
 
 ### `"array"`

diff --git a/packages/eslint-plugin/docs/rules/await-thenable.md b/packages/eslint-plugin/docs/rules/await-thenable.md
@@ -33,19 +33,6 @@ const createValue = async () => 'value';
 await createValue();
 ```
 
-## Options
-
-```jsonc
-// .eslintrc.json
-{
-  "rules": {
-    "@typescript-eslint/await-thenable": "error"
-  }
-}
-```
-
-This rule is not configurable.
-
 ## When Not To Use It
 
 If you want to allow code to `await` non-Promise values.

diff --git a/packages/eslint-plugin/docs/rules/ban-ts-comment.md b/packages/eslint-plugin/docs/rules/ban-ts-comment.md
@@ -21,32 +21,10 @@ The directive comments supported by TypeScript are:
 ## Rule Details
 
 This rule lets you set which directive comments you want to allow in your codebase.
-By default, only `@ts-check` is allowed, as it enables rather than suppresses errors.
-
-The configuration looks like this:
 
-```ts
-type DirectiveConfig =
-  | boolean
-  | 'allow-with-description'
-  | { descriptionFormat: string };
-
-interface Options {
-  'ts-expect-error'?: DirectiveConfig;
-  'ts-ignore'?: DirectiveConfig;
-  'ts-nocheck'?: DirectiveConfig;
-  'ts-check'?: DirectiveConfig;
-  minimumDescriptionLength?: number;
-}
+## Options
 
-const defaultOptions: Options = {
-  'ts-expect-error': 'allow-with-description',
-  'ts-ignore': true,
-  'ts-nocheck': true,
-  'ts-check': false,
-  minimumDescriptionLength: 3,
-};
-```
+By default, only `@ts-check` is allowed, as it enables rather than suppresses errors.
 
 ### `ts-expect-error`, `ts-ignore`, `ts-nocheck`, `ts-check` directives
 

diff --git a/packages/eslint-plugin/docs/rules/ban-tslint-comment.md b/packages/eslint-plugin/docs/rules/ban-tslint-comment.md
@@ -34,19 +34,6 @@ someCode(); // tslint:disable-line
 someCode(); // This is a comment that just happens to mention tslint
 ```
 
-## Options
-
-```jsonc
-// .eslintrc.json
-{
-  "rules": {
-    "@typescript-eslint/ban-tslint-comment": "warn"
-  }
-}
-```
-
-This rule is not configurable.
-
 ## When Not To Use It
 
 If you are still using TSLint.
diff --git a/packages/eslint-plugin/docs/rules/ban-types.md b/packages/eslint-plugin/docs/rules/ban-types.md
@@ -6,80 +6,61 @@ description: 'Disallow certain types.'
 >
 > See **https://typescript-eslint.io/rules/ban-types** for documentation.
 
-Some builtin types have aliases, some types are considered dangerous or harmful.
+Some built-in types have aliases, while some types are considered dangerous or harmful.
 It's often a good idea to ban certain types to help with consistency and safety.
 
 ## Rule Details
 
 This rule bans specific types and can suggest alternatives.
 Note that it does not ban the corresponding runtime objects from being used.
 
-## Options
-
-```ts
-type Options = {
-  types?: {
-    [typeName: string]:
-      | false
-      | string
-      | {
-          message: string;
-          fixWith?: string;
-        };
-  };
-  extendDefaults?: boolean;
-};
-```
-
-The rule accepts a single object as options.
-
-### `types`
+Examples of code with the default options:
 
-An object whose keys are the types you want to ban, and the values are error messages.
+<!--tabs-->
 
-The type can either be a type name literal (`Foo`), a type name with generic parameter instantiation(s) (`Foo<Bar>`), the empty object literal (`{}`), or the empty tuple type (`[]`).
+### ❌ Incorrect
 
-The values can be:
+```ts
+// use lower-case primitives for consistency
+const str: String = 'foo';
+const bool: Boolean = true;
+const num: Number = 1;
+const symb: Symbol = Symbol('foo');
+const bigInt: BigInt = 1n;
 
-- A string, which is the error message to be reported; or
-- `false` to specifically un-ban this type (useful when you are using `extendDefaults`); or
-- An object with the following properties:
-  - `message: string` - the message to display when the type is matched.
-  - `fixWith?: string` - a string to replace the banned type with when the fixer is run. If this is omitted, no fix will be done.
+// use a proper function type
+const func: Function = () => 1;
 
-### `extendDefaults`
+// use safer object types
+const lowerObj: Object = {};
+const capitalObj: Object = { a: 'string' };
 
-If you're specifying custom `types`, you can set this to `true` to extend the default `types` configuration. This is a convenience option to save you copying across the defaults when adding another type.
+const curly1: {} = 1;
+const curly2: {} = { a: 'string' };
+```
 
-If this is `false`, the rule will _only_ use the types defined in your configuration.
+### ✅ Correct
 
-Example configuration:
+```ts
+// use lower-case primitives for consistency
+const str: string = 'foo';
+const bool: boolean = true;
+const num: number = 1;
+const symb: symbol = Symbol('foo');
+const bigInt: bigint = 1n;
 
-```jsonc
-{
-  "@typescript-eslint/ban-types": [
-    "error",
-    {
-      "types": {
-        // add a custom message to help explain why not to use it
-        "Foo": "Don't use Foo because it is unsafe",
+// use a proper function type
+const func: () => number = () => 1;
 
-        // add a custom message, AND tell the plugin how to fix it
-        "OldAPI": {
-          "message": "Use NewAPI instead",
-          "fixWith": "NewAPI"
-        },
+// use safer object types
+const lowerObj: object = {};
+const capitalObj: { a: string } = { a: 'string' };
 
-        // un-ban a type that's banned by default
-        "{}": false
-      },
-      "extendDefaults": true
-    }
-  ]
-}
+const curly1: number = 1;
+const curly2: Record<'a', string> = { a: 'string' };
 ```
 
-### Default Options
+## Options
 
 The default options provide a set of "best practices", intended to provide safety and standardization in your codebase:
 
@@ -122,7 +103,6 @@ const defaultTypes = {
     message: 'Use bigint instead',
     fixWith: 'bigint',
   },
-
   Function: {
     message: [
       'The `Function` type accepts any function-like value.',
@@ -131,7 +111,6 @@ const defaultTypes = {
       'If you are expecting the function to accept certain arguments, you should explicitly define the function shape.',
     ].join('\n'),
   },
-
   // object typing
   Object: {
     message: [
@@ -152,52 +131,48 @@ const defaultTypes = {
 
 </details>
 
-### Examples
-
-Examples of code with the default options:
-
-<!--tabs-->
+### `types`
 
-#### ❌ Incorrect
+An object whose keys are the types you want to ban, and the values are error messages.
 
-```ts
-// use lower-case primitives for consistency
-const str: String = 'foo';
-const bool: Boolean = true;
-const num: Number = 1;
-const symb: Symbol = Symbol('foo');
-const bigInt: BigInt = 1n;
+The type can either be a type name literal (`Foo`), a type name with generic parameter instantiation(s) (`Foo<Bar>`), the empty object literal (`{}`), or the empty tuple type (`[]`).
 
-// use a proper function type
-const func: Function = () => 1;
+The values can be:
 
-// use safer object types
-const capitalObj1: Object = 1;
-const capitalObj2: Object = { a: 'string' };
+- A string, which is the error message to be reported; or
+- `false` to specifically un-ban this type (useful when you are using `extendDefaults`); or
+- An object with the following properties:
+  - `message: string` - the message to display when the type is matched.
+  - `fixWith?: string` - a string to replace the banned type with when the fixer is run. If this is omitted, no fix will be done.
 
-const curly1: {} = 1;
-const curly2: {} = { a: 'string' };
-```
+### `extendDefaults`
 
-#### ✅ Correct
+If you're specifying custom `types`, you can set this to `true` to extend the default `types` configuration. This is a convenience option to save you copying across the defaults when adding another type.
 
-```ts
-// use lower-case primitives for consistency
-const str: string = 'foo';
-const bool: boolean = true;
-const num: number = 1;
-const symb: symbol = Symbol('foo');
-const bigInt: bigint = 1n;
+If this is `false`, the rule will _only_ use the types defined in your configuration.
 
-// use a proper function type
-const func: () => number = () => 1;
+Example configuration:
 
-// use safer object types
-const lowerObj: object = {};
+```jsonc
+{
+  "@typescript-eslint/ban-types": [
+    "error",
+    {
+      "types": {
+        // add a custom message to help explain why not to use it
+        "Foo": "Don't use Foo because it is unsafe",
 
-const capitalObj1: number = 1;
-const capitalObj2: { a: string } = { a: 'string' };
+        // add a custom message, AND tell the plugin how to fix it
+        "OldAPI": {
+          "message": "Use NewAPI instead",
+          "fixWith": "NewAPI"
+        },
 
-const curly1: number = 1;
-const curly2: Record<'a', string> = { a: 'string' };
+        // un-ban a type that's banned by default
+        "{}": false
+      },
+      "extendDefaults": true
+    }
+  ]
+}
 ```