eslint-doc-generator

eslint-doc-generator

Automatic documentation generator for ESLint plugins and rules.

Generates the following documentation based on ESLint and top ESLint plugin conventions:

• README.md rules table
• Rule doc titles and config/fixable/etc. notices

Also performs some basic section consistency checks on rule docs:

• Contains an ## Options / ## Config section and mentions each named option (for rules with options)

Used by popular ESLint plugins like:

• eslint-plugin-ava
• eslint-plugin-ember
• eslint-plugin-eslint-plugin
• eslint-plugin-jsx-a11y
• eslint-plugin-qunit
• eslint-plugin-react
• eslint-plugin-unicorn

Motivation

• Standardize documentation across thousands of ESLint plugins and rules
• Improve the discoverability of key rule information and thus rule usability
• Streamline the process of adding new rules by automating part of the documentation
• Eliminate the custom documentation scripts and tests previously built and maintained by many ESLint plugins

Setup

Install it:

npm i --save-dev eslint-doc-generator

Add scripts to package.json:

• Both a lint script to ensure everything is up-to-date in CI and an update script for contributors to run locally
• Add any config options in the update:eslint-docs script only
• Alternative scripts may be needed with build tools or prettier

{
  "scripts": {
    "lint": "npm-run-all \"lint:*\"",
    "lint:docs": "markdownlint \"**/*.md\"",
    "lint:eslint-docs": "npm-run-all \"update:eslint-docs -- --check\"",
    "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 auto-generated rules list -->
<!-- end auto-generated 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).

<!-- end auto-generated rule header -->

And be sure to enable the recommended rules from eslint-plugin-eslint-plugin as well as eslint-plugin/require-meta-docs-description to ensure your rules have consistent descriptions for use in the generated docs.

Usage

Run the script from package.json to start out or any time you add a rule or update rule metadata in your plugin:

npm run update:eslint-docs

Example

Generated content in a rule doc (everything above the marker comment) (intentionally showing all possible notices):

# Disallow using foo (`test/no-foo`)

✅ This rule is enabled in the `recommended` config.

💼 This rule is enabled in the following configs: ✅ `recommended`, 🎨 `stylistic`.

🎨<sup>⚠️</sup> This rule _warns_ in the `stylistic` config.

🎨<sup>🚫</sup> This rule is _disabled_ in the `stylistic` config.

🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/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 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).

💭 This rule requires type information.

❗ This rule identifies problems that could cause errors or unexpected behavior.

📖 This rule identifies potential improvements.

📏 This rule focuses on code formatting.

❌ This rule is deprecated. It was replaced by [prefer-bar](prefer-bar.md).

<!-- end auto-generated rule header -->

Description.

## Examples

Examples.

...

Generated rules table in README.md (everything between the marker comments) (intentionally showing all possible columns):

# eslint-plugin-test

## Rules

<!-- begin auto-generated rules list -->

💼 Configurations enabled in.\
✅ Enabled in the `recommended` configuration.\
✅<sup>⚠️</sup> Warns in the `recommended` configuration.\
✅<sup>🚫</sup> Disabled in the `recommended` configuration.\
🎨 Enabled in the `stylistic` configuration.\
🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\
💡 Manually fixable by [editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).\
💭 Requires type information.\
🗂️ The type of rule.\
❗ Identifies problems that could cause errors or unexpected behavior.\
📖 Identifies potential improvements.\
📏 Focuses on code formatting.\
❌ Deprecated.

| Name                                     | Description        | 💼    | 🔧  | 💡  | 💭  | 🗂️  | ❌  |
| :--------------------------------------- | :----------------- | :---- | :-- | :-- | :-- | :-- | :-- |
| [no-foo](docs/rules/no-foo.md)           | disallow using foo | ✅    | 🔧  |     |     | ❗  |     |
| [prefer-bar](docs/rules/prefer-bar.md)   | enforce using bar  | ✅ 🎨 |     | 💡  | 💭  | 📖  |     |
| [require-baz](docs/rules/require-baz.md) | require using baz  |       | 🔧  |     |     | 📏  | ❌  |

<!-- end auto-generated 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.

Badge

While config emojis are recommended (see --config-emoji), you can alternatively define badges for configs at the bottom of your README.md.

Here's a badge for a custom fun config that displays in blue:

[fun]: https://img.shields.io/badge/-fun-blue.svg

And how it looks:

Configuration options

Name	Description
--check	Whether to check for and fail if there is a diff. No output will be written. Typically used during CI.
--config-emoji	Custom emoji to use for a config. Format is config-name,emoji. Default emojis are provided for common configs. To remove a default emoji and rely on a badge instead, provide the config name without an emoji. Option can be repeated.
--ignore-config	Config to ignore from being displayed. Often used for an all config. Option can be repeated.
--ignore-deprecated-rules	Whether to ignore deprecated rules from being checked, displayed, or updated (default: false).
--rule-doc-notices	Ordered, comma-separated list of notices to display in rule doc. Non-applicable notices will be hidden. Choices: configs, deprecated, fixable, fixableAndHasSuggestions, hasSuggestions, requiresTypeChecking, type (off by default). A consolidated notice called fixableAndHasSuggestions automatically replaces fixable and hasSuggestions when applicable. Default: deprecated,configs,fixable,fixableAndHasSuggestions,hasSuggestions,requiresTypeChecking.
--rule-doc-section-exclude	Disallowed section in each rule doc. Exit with failure if present. Option can be repeated.
--rule-doc-section-include	Required section in each rule doc. Exit with failure if missing. Option can be repeated.
--rule-doc-section-options	Whether to require an "Options" or "Config" rule doc section and mention of any named options for rules with options (default: true).
--rule-doc-title-format	The format to use for rule doc titles. Defaults to desc-parens-prefix-name. See choices in below table.
--rule-list-columns	Ordered, comma-separated list of columns to display in rule list. Empty columns will be hidden. Choices: configs, deprecated, description, fixable, hasSuggestions, name, requiresTypeChecking, type (off by default). Default: name,description,configs,fixable,hasSuggestions,requiresTypeChecking,deprecated.
--split-by	Rule property to split the rules list by. A separate list and header will be created for each value. Example: meta.type.
--url-configs	Link to documentation about the ESLint configurations exported by the plugin.

All options are optional.

--rule-doc-title-format

Where no-foo is the rule name, Disallow use of foo is the rule description, and eslint-plugin-test is the plugin name.

Value	Example
desc	# Disallow use of foo
desc-parens-name	# Disallow use of foo (no-foo)
desc-parens-prefix-name (default)	# Disallow use of foo (test/no-foo)
name	# no-foo
prefix-name	# test/no-foo

Compatibility

Build tools

If you have a build step for your code like Babel or TypeScript, you may need to adjust your scripts to run your build before this tool:

{
  "build": "tsc",
  "update:eslint-docs": "npm run build && eslint-doc-generator"
}

markdownlint

The output of this tool should be compatible with markdownlint which you might use to lint your markdown. However, if any of your ESLint configs disable your rules or set them to warn, you'll need to exempt the <sup> (superscript) element from no-inline-html:

{
  "no-inline-html": { "allowed_elements": ["sup"] }
}

prettier

If you use prettier to format your markdown, you may need to adjust your scripts to run prettier formatting after running this tool:

{
  "format": "prettier --write .",
  "lint:eslint-docs": "npm run update:eslint-docs && git diff --exit-code",
  "update:eslint-docs": "eslint-doc-generator && npm run format"
}

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

Changelog

v0.18.0 (2022-10-31)

:rocket: Enhancement

• #198 Indicate when a rule is set to off/warn by a config in the README rules list (@bmish)
• #199 Add default emoji for TypeScript configs, adjust default emoji for accessibility configs (@bmish)

:memo: Documentation

• #200 Demonstrage usage with a build step or prettier formatting (@bmish)

Committers: 1

• Bryan Mishkin (@bmish)