docs: automate docs with eslint-doc-generator

Author: bmish

.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",
 

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

README.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:

docs/rules/consistent-type-specifier-style.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.
 

docs/rules/default.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.

docs/rules/dynamic-import-chunkname.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

docs/rules/export.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.
 
 

docs/rules/exports-last.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.

docs/rules/extensions.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.