eslint-doc-generator
Automatic documentation generator for ESLint plugins and rules.
Generates the following documentation based on ESLint and top ESLint plugin conventions:
README.mdrules table- Rule doc titles and notices
Also performs some basic section consistency checks on rule docs:
- Contains an
## Options/## Configsection and mentions each named option (for rules with options)
Setup
Install it:
npm i --save-dev eslint-doc-generator
Add it as as script in package.json (included as a lint script to demonstrate how we can ensure it passes and is up-to-date in CI):
{
"scripts": {
"lint": "npm-run-all \"lint:*\"",
"lint:docs": "markdownlint \"**/*.md\"",
"lint:eslint-docs": "npm-run-all update:eslint-docs && git diff --exit-code",
"lint:js": "eslint .",
"update:eslint-docs": "eslint-doc-generator"
}
}
Delete any old rules list from your README.md. A new one will be automatically added to your ## Rules section (along with the following marker comments if they don't already exist):
<!-- begin rules list -->
<!-- end rules list -->
Delete any old recommended/fixable/etc. notices from your rule docs. A new title and notices will be automatically added to the top of each rule doc (along with a marker comment if it doesn't exist yet).
Usage
Run the script from package.json:
npm run update:eslint-docs
Example
Generated content in a rule doc (everything above the marker comment):
# Disallow use of `foo` (`test/no-foo`)
💼 This rule is enabled in the following configs: `all`, `recommended`.
🔧 This rule is automatically fixable by the `--fix` [CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
💡 This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
❌ This rule is deprecated. It was replaced by [some-new-rule](some-new-rule.md).
<!-- end rule header -->
Description.
## Examples
Examples.
...
Generated rules table in README.md (everything between the marker comments):
# eslint-plugin-test
## Rules
<!-- begin rules list -->
✅ Enabled in the `recommended` configuration.\
💼 Configurations enabled in.\
🔧 Automatically fixable by the `--fix` [CLI option](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems).\
💡 Manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).\
💭 Requires type information.\
❌ Deprecated.
| Rule | Description | ✅ | 🔧 | 💡 | 💭 |
| :------------------------------------------------------------- | :------------------------------------------------ | :-- | :-- | :-- | :-- |
| [max-nested-describe](docs/rules/max-nested-describe.md) | Enforces a maximum depth to nested describe calls | | | | |
| [no-alias-methods](docs/rules/no-alias-methods.md) | Disallow alias methods | ✅ | 🔧 | | |
| [no-commented-out-tests](docs/rules/no-commented-out-tests.md) | Disallow commented out tests | ✅ | | | |
<!-- end rules list -->
...
The table will hide columns that don't apply to any rules, and the legend will include only the symbols that are used in the table.
If you have any custom configs (besides all, recommended), you'll need to define a badge for them at the bottom of your README.md. Here's a badge for a custom style config that displays in blue:
[style]: https://img.shields.io/badge/-style-blue.svg
Configuration options
| Name | Description |
|---|---|
--ignore-config |
(optional) Config to ignore from being displayed (often used for an all config) (option can be repeated). |
--ignore-deprecated-rules |
(optional) Whether to ignore deprecated rules from being checked, displayed, or updated (default: false). |
--rule-doc-section-include |
(optional) Required section in each rule doc (option can be repeated). |
--rule-doc-section-exclude |
(optional) Disallowed section in each rule doc (option can be repeated). |
--rule-doc-title-format |
(optional) The format to use for rule doc titles. Choices: desc-parens-prefix-name (default), desc, desc-parens-name, name, prefix-name. |
--url-configs |
(optional) Link to documentation about the ESLint configurations exported by the plugin. |
Upcoming features
- Custom config emojis (#34)
Related
- eslint-plugin-eslint-plugin - Linter for ESLint plugins (related list)
- generator-eslint - Generates initial ESLint plugin and rule files but without the sophisticated documentation provided by eslint-doc-generator
![[BUG] Prettier not found](https://avatars.githubusercontent.com/u/38396609?v=4)
5 Nov 22, 2022
5 Dec 5, 2022
3 May 18, 2022
4 May 3, 2022
14 Jan 3, 2023
6 Oct 28, 2022
7 Dec 7, 2022
21 May 6, 2022
153 Jan 2, 2023
20 Aug 16, 2022
356 Dec 29, 2022
16 Dec 6, 2022
24 Dec 17, 2022
6 Jan 6, 2023
11 Dec 30, 2022
6 Oct 26, 2022
367 Jan 4, 2023
44 Oct 29, 2022
7 Apr 28, 2022