[Docs] automate docs with eslint-doc-generator

jorisw · Oct 29, 2022 · e85c694 · e85c694
1 parent c3d14cb
commit e85c694
Show file tree

Hide file tree

Showing 95 changed files with 344 additions and 141 deletions.
diff --git a/.eslintrc b/.eslintrc
@@ -71,6 +71,7 @@
         "eslint-plugin/no-deprecated-report-api": "off",
         "eslint-plugin/prefer-replace-text": "error",
         "eslint-plugin/report-message-format": "error",
+        "eslint-plugin/require-meta-docs-description": ["error", { "pattern": "^(Enforce|Ensure|Prefer|Forbid).+\\.$" }],
         "eslint-plugin/require-meta-schema": "error",
         "eslint-plugin/require-meta-type": "error",
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -45,6 +45,7 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
 - [readme] make json for setting groups multiline ([#2570], thanks [@bertyhell])
 - [Tests] [`no-restricted-paths`]: Tests for `import type` statements ([#2459], thanks [@golergka])
 - [Tests] [`no-restricted-paths`]: fix one failing `import type` test case, submitted by [@golergka], thanks [@azyzz228]
+- [Docs] automate docs with eslint-doc-generator ([#2582], thanks [@bmish])
 
 ## [2.26.0] - 2022-04-05
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,10 +5,12 @@ Thanks for your interest in helping out! Here are a **few** _weird_ tricks to ~~
 ## TL;DR: Checklist
 
 When opening an [issue](#issues):
+
 - [ ] search open/closed issues
 - [ ] discuss bug/enhancement in new or old issue
 
 [PR](#prs) time:
+
 - [ ] write tests
 - [ ] implement feature/fix bug
 - [ ] update docs
@@ -18,13 +20,13 @@ Remember, you don't need to do it all yourself; any of these are helpful! 😎
 
 ## Issues
 
-### Search open + closed issues for similar cases.
+### Search open + closed issues for similar cases
 
   You may find an open issue that closely matches what you are thinking. You may also find a closed issue with discussion that either solves your problem or explains why we are unlikely to solve it in the near future.
 
   If you find a matching issue that is open, and marked `accepted` and/or `help wanted`, you might want to [open a PR](#prs).
 
-### Open an issue.
+### Open an issue
 
   Let's discuss your issue. Could be as simple as unclear documentation or a wonky config file.
   If you're suggesting a feature, it might exist and need better documentation, or it might be in process. Even given those, some discussion might be warranted to ensure the enhancement is clear.
@@ -48,21 +50,19 @@ Here are some things to keep in mind when working on a PR:
 If a PR is open, but unfortunately the author is, for any reason, not available to apply code review fixes or rebase the source branch, then please **do not open a new PR**.
 Instead, paste a link to your own branch in the PR, and the maintainers can pull in your changes and update the existing PR in-place.
 
-#### Tests
+### Tests
 
 A PR that is just failing test cases for an existing issue is very helpful, as this can take as much time (if not more) as it takes to implement a new feature or fix a bug.
 
 If you only have enough time to write tests, fantastic! Submit away. This is a great jumping-off point for a core contributor or even another PR to continue what you've started.
 
-#### Docs
-
-For enhancements to rules, please update the docs in `docs/rules` matching the rule filename from `src/rules`.
+### Docs
 
-Also, take a quick look at the rule summary in [README.md] in case it could use tweaking, or add a line if you've implemented a new rule.
+For enhancements to rules, please update the docs in `docs/rules` matching the rule filename from `src/rules` or the rule description in `meta.docs.description`. Running `npm run update:eslint-docs` will update the [README.md] and rule doc header.
 
 Bugfixes may not warrant docs changes, though it's worth skimming the existing docs to see if there are any relevant caveats that need to be removed.
 
-#### Changelog
+### Changelog
 
 Please add a quick blurb to the [**Unreleased**](./CHANGELOG.md#unreleased) section of the change log. Give yourself some credit, and please link back to the PR for future reference. This is especially helpful for resolver changes, as the resolvers are less frequently modified and published.
 
@@ -72,4 +72,4 @@ Note also that the change log can't magically link back to Github entities (i.e.
 
 Please familiarize yourself with the [Code of Conduct](https://github.com/import-js/.github/blob/main/CODE_OF_CONDUCT.md).
 
-[README.md]: ./README.md
+[README.md]: ./README.md
diff --git a/README.md b/README.md
diff --git a/docs/rules/consistent-type-specifier-style.md b/docs/rules/consistent-type-specifier-style.md
@@ -1,5 +1,9 @@
 # import/consistent-type-specifier-style
 
+🔧 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 -->
+
 In both Flow and TypeScript you can mark an import as a type-only import by adding a "kind" marker to the import. Both languages support two positions for marker.
 
 **At the top-level** which marks all names in the import as type-only and applies to named, default, and namespace (for TypeScript) specifiers:

diff --git a/docs/rules/default.md b/docs/rules/default.md
@@ -1,5 +1,9 @@
 # import/default
 
+💼 This rule is enabled in the following configs: ❗ `errors`, ☑️ `recommended`.
+
+<!-- end auto-generated rule header -->
+
 If a default import is requested, this rule will report if there is no default
 export in the imported module.
 

diff --git a/docs/rules/dynamic-import-chunkname.md b/docs/rules/dynamic-import-chunkname.md
@@ -1,5 +1,7 @@
 # import/dynamic-import-chunkname
 
+<!-- end auto-generated rule header -->
+
 This rule reports any dynamic imports without a webpackChunkName specified in a leading block comment in the proper format.
 
 This rule enforces naming of webpack chunks in dynamic imports. When you don't explicitly name chunks, webpack will autogenerate chunk names that are not consistent across builds, which prevents long-term browser caching.

diff --git a/docs/rules/export.md b/docs/rules/export.md
@@ -1,5 +1,9 @@
 # import/export
 
+💼 This rule is enabled in the following configs: ❗ `errors`, ☑️ `recommended`.
+
+<!-- end auto-generated rule header -->
+
 Reports funny business with exports, like repeated exports of names or defaults.
 
 ## Rule Details

diff --git a/docs/rules/exports-last.md b/docs/rules/exports-last.md
@@ -1,5 +1,7 @@
 # import/exports-last
 
+<!-- end auto-generated rule header -->
+
 This rule enforces that all exports are declared at the bottom of the file. This rule will report any export declarations that comes before any non-export statements.
 
 

diff --git a/docs/rules/extensions.md b/docs/rules/extensions.md
@@ -1,4 +1,6 @@
-# import/extensions - Ensure consistent use of file extension within the import path
+# import/extensions
+
+<!-- end auto-generated rule header -->
 
 Some file resolve algorithms allow you to omit the file extension within the import source path. For example the `node` resolver can resolve `./foo/bar` to the absolute path `/User/someone/foo/bar.js` because the `.js` extension is resolved automatically by default. Depending on the resolver you can configure more extensions to get resolved automatically.
 
@@ -37,6 +39,7 @@ By providing both a string and an object, the string will set the default settin
 For example, `["error", "never", { "svg": "always" }]` would require that all extensions are omitted, except for "svg".
 
 `ignorePackages` can be set as a separate boolean option like this:
+
 ```
 "import/extensions": [
   <severity>,
@@ -49,10 +52,10 @@ For example, `["error", "never", { "svg": "always" }]` would require that all ex
   }
 ]
 ```
+
 In that case, if you still want to specify extensions, you can do so inside the **pattern** property.
 Default value of `ignorePackages` is `false`.
 
-
 ### Exception
 
 When disallowing the use of certain extensions this rule makes an exception and allows the use of extension when the file would not be resolvable without extension.

diff --git a/docs/rules/first.md b/docs/rules/first.md
@@ -1,5 +1,9 @@
 # import/first
 
+🔧 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 -->
+
 This rule reports any imports that come after non-import
 statements.
 

diff --git a/docs/rules/group-exports.md b/docs/rules/group-exports.md
@@ -1,5 +1,7 @@
 # import/group-exports
 
+<!-- end auto-generated rule header -->
+
 Reports when named exports are not grouped together in a single `export` declaration or when multiple assignments to CommonJS `module.exports` or `exports` object are present in a single file.
 
 **Rationale:** An `export` declaration or `module.exports` assignment can appear anywhere in the code. By requiring a single export declaration all your exports will remain at one place, making it easier to see what exports a module provides.

diff --git a/docs/rules/imports-first.md b/docs/rules/imports-first.md
@@ -1,3 +1,9 @@
 # import/imports-first
 
+❌ This rule is deprecated.
+
+🔧 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 -->
+
 This rule was **deprecated** in eslint-plugin-import v2.0.0. Please use the corresponding rule [`first`](https://github.com/import-js/eslint-plugin-import/blob/HEAD/docs/rules/first.md).
diff --git a/docs/rules/max-dependencies.md b/docs/rules/max-dependencies.md
@@ -1,5 +1,7 @@
 # import/max-dependencies
 
+<!-- end auto-generated rule header -->
+
 Forbid modules to have too many dependencies (`import` or `require` statements).
 
 This is a useful rule because a module with too many dependencies is a code smell, and usually indicates the module is doing too much and/or should be broken up into smaller modules.

diff --git a/docs/rules/named.md b/docs/rules/named.md
@@ -1,5 +1,9 @@
 # import/named
 
+💼🚫 This rule is enabled in the following configs: ❗ `errors`, ☑️ `recommended`. This rule is _disabled_ in the ⌨️ `typescript` config.
+
+<!-- end auto-generated rule header -->
+
 Verifies that all named imports are part of the set of named exports in the referenced module.
 
 For `export`, verifies that all named exports exist in the referenced module.

diff --git a/docs/rules/namespace.md b/docs/rules/namespace.md
@@ -1,5 +1,9 @@
 # import/namespace
 
+💼 This rule is enabled in the following configs: ❗ `errors`, ☑️ `recommended`.
+
+<!-- end auto-generated rule header -->
+
 Enforces names exist at the time they are dereferenced, when imported as a full namespace (i.e. `import * as foo from './foo'; foo.bar();` will report if `bar` is not exported by `./foo`.).
 
 Will report at the import declaration if there are _no_ exported names found.

diff --git a/docs/rules/newline-after-import.md b/docs/rules/newline-after-import.md
@@ -1,5 +1,9 @@
 # import/newline-after-import
 
+🔧 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 -->
+
 Enforces having one or more empty lines after the last top-level import statement or require call.
 +(fixable) The `--fix` option on the [command line] automatically fixes problems reported by this rule.
 

diff --git a/docs/rules/no-absolute-path.md b/docs/rules/no-absolute-path.md
@@ -1,7 +1,11 @@
-# import/no-absolute-path: Forbid import of modules using absolute paths
+# import/no-absolute-path
+
+<!-- end auto-generated rule header -->
 
 Node.js allows the import of modules using an absolute path such as `/home/xyz/file.js`. That is a bad practice as it ties the code using it to your computer, and therefore makes it unusable in packages distributed on `npm` for instance.
 
+This rule forbids the import of modules using absolute paths.
+
 ## Rule Details
 
 ### Fail

diff --git a/docs/rules/no-amd.md b/docs/rules/no-amd.md
@@ -1,5 +1,7 @@
 # import/no-amd
 
+<!-- end auto-generated rule header -->
+
 Reports `require([array], ...)` and `define([array], ...)` function calls at the
 module scope. Will not report if !=2 arguments, or first argument is not a literal array.
 

diff --git a/docs/rules/no-anonymous-default-export.md b/docs/rules/no-anonymous-default-export.md
@@ -1,5 +1,7 @@
 # import/no-anonymous-default-export
 
+<!-- end auto-generated rule header -->
+
 Reports if a module's default export is unnamed. This includes several types of unnamed data types; literals, object expressions, arrays, anonymous functions, arrow functions, and anonymous class declarations.
 
 Ensuring that default exports are named helps improve the grepability of the codebase by encouraging the re-use of the same identifier for the module's default export at its declaration site and at its import sites.

diff --git a/docs/rules/no-commonjs.md b/docs/rules/no-commonjs.md
@@ -1,5 +1,7 @@
 # import/no-commonjs
 
+<!-- end auto-generated rule header -->
+
 Reports `require([string])` function calls. Will not report if >1 argument,
 or single argument is not a literal string.
 

diff --git a/docs/rules/no-cycle.md b/docs/rules/no-cycle.md
@@ -1,5 +1,7 @@
 # import/no-cycle
 
+<!-- end auto-generated rule header -->
+
 Ensures that there is no resolvable path back to this module via its dependencies.
 
 This includes cycles of depth 1 (imported module imports me) to `"∞"` (or `Infinity`), if the

diff --git a/docs/rules/no-default-export.md b/docs/rules/no-default-export.md
@@ -1,4 +1,6 @@
-# `import/no-default-export`
+# import/no-default-export
+
+<!-- end auto-generated rule header -->
 
 Prohibit default exports. Mostly an inverse of [`prefer-default-export`].
 

diff --git a/docs/rules/no-deprecated.md b/docs/rules/no-deprecated.md
@@ -1,4 +1,6 @@
-# `import/no-deprecated`
+# import/no-deprecated
+
+<!-- end auto-generated rule header -->
 
 Reports use of a deprecated name, as indicated by a JSDoc block with a `@deprecated`
 tag or TomDoc `Deprecated: ` comment.

diff --git a/docs/rules/no-duplicates.md b/docs/rules/no-duplicates.md
@@ -1,5 +1,11 @@
 # import/no-duplicates
 
+⚠️ This rule _warns_ in the following configs: ☑️ `recommended`, 🚸 `warnings`.
+
+🔧 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 -->
+
 Reports if a resolved path is imported more than once.
 +(fixable) The `--fix` option on the [command line] automatically fixes some problems reported by this rule.
 

diff --git a/docs/rules/no-dynamic-require.md b/docs/rules/no-dynamic-require.md
@@ -1,8 +1,10 @@
-# import/no-dynamic-require: Forbid `require()` calls with expressions
+# import/no-dynamic-require
+
+<!-- end auto-generated rule header -->
 
 The `require` method from CommonJS is used to import modules from different files. Unlike the ES6 `import` syntax, it can be given expressions that will be resolved at runtime. While this is sometimes necessary and useful, in most cases it isn't. Using expressions (for instance, concatenating a path and variable) as the argument makes it harder for tools to do static code analysis, or to find where in the codebase a module is used.
 
-This rule checks every call to `require()` that uses expressions for the module name argument.
+This rule forbids every call to `require()` that uses expressions for the module name argument.
 
 ## Rule Details
 

diff --git a/docs/rules/no-empty-named-blocks.md b/docs/rules/no-empty-named-blocks.md
@@ -1,5 +1,9 @@
 # import/no-empty-named-blocks
 
+🔧💡 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) and manually fixable by [editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+
+<!-- end auto-generated rule header -->
+
 Reports the use of empty named import blocks.
 
 ## Rule Details

diff --git a/docs/rules/no-extraneous-dependencies.md b/docs/rules/no-extraneous-dependencies.md
@@ -1,4 +1,6 @@
-# import/no-extraneous-dependencies: Forbid the use of extraneous packages
+# import/no-extraneous-dependencies
+
+<!-- end auto-generated rule header -->
 
 Forbid the import of external modules that are not declared in the `package.json`'s `dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies`, or `bundledDependencies`.
 The closest parent `package.json` will be used. If no `package.json` is found, the rule will not lint anything. This behavior can be changed with the rule option `packageDir`. Normally ignores imports of modules marked internal, but this can be changed with the rule option `includeInternal`. Type imports can be verified by specifying `includeTypes`.

diff --git a/docs/rules/no-import-module-exports.md b/docs/rules/no-import-module-exports.md
@@ -1,5 +1,9 @@
 # import/no-import-module-exports
 
+🔧 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 -->
+
 Reports the use of import declarations with CommonJS exports in any module
 except for the [main module](https://docs.npmjs.com/files/package.json#main).
 

diff --git a/docs/rules/no-internal-modules.md b/docs/rules/no-internal-modules.md
@@ -1,5 +1,7 @@
 # import/no-internal-modules
 
+<!-- end auto-generated rule header -->
+
 Use this rule to prevent importing the submodules of other modules.
 
 ## Rule Details

diff --git a/docs/rules/no-mutable-exports.md b/docs/rules/no-mutable-exports.md
@@ -1,5 +1,7 @@
 # import/no-mutable-exports
 
+<!-- end auto-generated rule header -->
+
 Forbids the use of mutable exports with `var` or `let`.
 
 ## Rule Details

diff --git a/docs/rules/no-named-as-default-member.md b/docs/rules/no-named-as-default-member.md
@@ -1,5 +1,9 @@
 # import/no-named-as-default-member
 
+⚠️ This rule _warns_ in the following configs: ☑️ `recommended`, 🚸 `warnings`.
+
+<!-- end auto-generated rule header -->
+
 Reports use of an exported name as a property on the default export.
 
 Rationale: Accessing a property that has a name that is shared by an exported

diff --git a/docs/rules/no-named-as-default.md b/docs/rules/no-named-as-default.md
@@ -1,5 +1,9 @@
 # import/no-named-as-default
 
+⚠️ This rule _warns_ in the following configs: ☑️ `recommended`, 🚸 `warnings`.
+
+<!-- end auto-generated rule header -->
+
 Reports use of an exported name as the locally imported name of a default export.
 
 Rationale: using an exported name as the name of the default export is likely...

diff --git a/docs/rules/no-named-default.md b/docs/rules/no-named-default.md
@@ -1,5 +1,7 @@
 # import/no-named-default
 
+<!-- end auto-generated rule header -->
+
 Reports use of a default export as a locally named import.
 
 Rationale: the syntax exists to import default exports expressively, let's use it.

diff --git a/docs/rules/no-named-export.md b/docs/rules/no-named-export.md
@@ -1,4 +1,6 @@
-# `import/no-named-export`
+# import/no-named-export
+
+<!-- end auto-generated rule header -->
 
 Prohibit named exports. Mostly an inverse of [`no-default-export`].
 

diff --git a/docs/rules/no-namespace.md b/docs/rules/no-namespace.md
@@ -1,5 +1,9 @@
 # import/no-namespace
 
+🔧 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 -->
+
 Enforce a convention of not using namespace (a.k.a. "wildcard" `*`) imports.
 
 +(fixable) The `--fix` option on the [command line] automatically fixes problems reported by this rule, provided that the namespace object is only used for direct member access, e.g. `namespace.a`.