eslint-doc-generator

eslint-doc-generator

Automatic documentation generator for ESLint plugins and rules. Inspired by documentation conventions from ESLint and top ESLint plugins.

Generates the following documentation covering a wide variety of rule metadata:

• README.md rules table
• Rule doc titles and notices

Also performs configurable section consistency checks on rule docs:

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

Table of contents

• Motivation
• Setup
• Usage
• Examples
  • Rules list table
  • Rule doc notices
  • Users
• Configuration options
  • Column and notice types
  • --rule-doc-title-format
  • Configuration file
  • Badges
• Compatibility
  • Build tools
  • prettier
• Semantic versioning policy
• Related

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/updating rules while ensuring documentation is kept up-to-date
• 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 (or use a config file)
• 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 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 already exist).

<!-- 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
• eslint-plugin/require-meta-docs-url to ensure your rule docs are linked to by editors on highlighted violations

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

Examples

For examples, see our users or the in-house examples below. Note that the in-house examples intentionally show all possible columns and notices.

Rules list table

See the generated rules table and legend in our example README.md.

Rule doc notices

See the generated rule doc title and notices in our example rule docs no-foo.md, prefer-bar.md, require-baz.md.

Users

This tool is used by popular ESLint plugins like:

• eslint-plugin-ava
• eslint-plugin-ember
• eslint-plugin-eslint-plugin
• eslint-plugin-import
• eslint-plugin-jest
• eslint-plugin-jsx-a11y
• eslint-plugin-promise
• eslint-plugin-qunit
• eslint-plugin-react
• eslint-plugin-unicorn

Configuration options

These can be provided as CLI options or as config file options. All options are optional.

The CLI has an optional path argument if you need to point the CLI to an ESLint plugin directory that isn't just the current directory.

There's also a postprocess option that's only available via a config file.

Name	Description
--check	Whether to check for and fail if there is a diff. No output will be written. Typically used during CI. Default: false.
--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.
--init-rule-docs	Whether to create rule doc files if they don't yet exist. Default: false.
--path-rule-doc	Path to markdown file for each rule doc. Use {name} placeholder for the rule name. Default: docs/rules/{name}.md.
--path-rule-list	Path to markdown file where the rules table list should live. Default: README.md. Option can be repeated.
--rule-doc-notices	Ordered, comma-separated list of notices to display in rule doc. Non-applicable notices will be hidden. See choices in below table. Default: deprecated,configs,fixableAndHasSuggestions,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. See choices in below table. Default: name,description,configsError,configsWarn,configsOff,fixable,hasSuggestions,requiresTypeChecking,deprecated.
--rule-list-split	Rule property(s) to split the rules list by. A separate list and header will be created for each value. Example: meta.type. A function can also be provided for this option via a config file.
--url-configs	Link to documentation about the ESLint configurations exported by the plugin.
--url-rule-doc	Link to documentation for each rule. Useful when it differs from the rule doc path on disk (e.g. custom documentation site in use). Use {name} placeholder for the rule name.

Column and notice types

These are the types of rule metadata that are available for display in rule list columns (--rule-list-columns) and/or rule doc notices (--rule-doc-notices).

Emoji	Type	Column?	Notice?	Description
💼	configsError	Yes	No	Whether a rule is set to error in a config.
🚫	configsOff	Yes	No	Whether a rule is set to off in a config.
⚠️	configsWarn	Yes	No	Whether a rule is set to warn in a config.
💼	configs	No	Yes	What configs set a rule to what severities.
❌	deprecated	Yes	Yes	Whether a rule is deprecated (i.e. likely to be removed/renamed in a future major version).
	description	Yes	Yes	The rule description.
🔧💡	fixableAndHasSuggestions	Yes	Yes	Whether a rule is fixable and/or has suggestions.
🔧	fixable	Yes	Yes	Whether a rule is fixable.
💡	hasSuggestions	Yes	Yes	Whether a rule has suggestions.
	name	Yes	No	The rule name.
⚙️	options	Yes	Yes	Whether a rule has options.
💭	requiresTypeChecking	Yes	Yes	Whether a rule requires type checking.
🗂️	type	Yes	Yes	The rule type (problem, suggestion, or layout).

--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

Configuration file

There are a few ways to create a config file (as an alternative to passing the options via CLI):

• An object exported by .eslint-doc-generatorrc.js, .eslint-doc-generatorrc.json, or any other config file format/name supported by cosmiconfig
• An object under the eslint-doc-generator key in package.json

Config files support all the CLI options but in camelCase.

Some options are exclusive to a JavaScript-based config file:

• postprocess - A function-only option useful for applying custom transformations such as formatting with tools like prettier. See prettier example.
• ruleListSplit with a function - This is useful for customizing the grouping of rules into lists.

Example .eslint-doc-generatorrc.js:

/** @type {import('eslint-doc-generator').GenerateOptions} */
const config = {
  ignoreConfig: ['all'],
};

module.exports = config;

Example .eslint-doc-generatorrc.js with ruleListSplit function:

/** @type {import('eslint-doc-generator').GenerateOptions} */
const config = {
  ruleListSplit(rules) {
    return [
      {
        // No header for this list.
        rules: rules.filter(([name, rule]) => !rule.meta.someProp),
      },
      {
        title: 'Foo',
        rules: rules.filter(([name, rule]) => rule.meta.someProp === 'foo'),
      },
      {
        title: 'Bar',
        rules: rules.filter(([name, rule]) => rule.meta.someProp === 'bar'),
      },
    ];
  },
};

module.exports = config;

Badges

While config emojis are the recommended representations of configs that a rule belongs to (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:

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

And how it looks:

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 to ensure the documentation is generated from the latest plugin information:

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

prettier

If you use prettier to format your markdown, you can provide a postprocess function to ensure the documentation generated by this tool is formatted correctly:

const prettier = require('prettier');
const { prettier: prettierRC } = require('./package.json'); // or wherever your prettier config lies

/** @type {import('eslint-doc-generator').GenerateOptions} */
const config = {
  postprocess: (content, path) =>
    prettier.format(content, { ...prettierRC, parser: 'markdown' }),
};

module.exports = config;

Alternatively, you can configure your scripts to run prettier after 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"
}

Semantic versioning policy

This tool follows semantic versioning.

New features will be released as a minor version, while bug fixes will be released as a patch version.

Breaking changes will be released as a major version and include:

• Changing an option default
• Renaming or removing an option
• Other backwards-incompatible changes to the CLI / API
• Raising Node or ESLint version requirements

Tweaks to the generated documentation output can take place in any type of release including minor and patch versions. This can break your build, as even a small formatting change will cause a diff, but you can simply re-run the tool to fix.

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

v1.2.0 (2022-12-21)

:rocket: Enhancement

• #365 Support a user-defined function for --rule-list-split option (@bmish)
• #351 Support splitting by multiple properties in --rule-list-split option (@bmish)

:bug: Bug Fix

• #357 Ensure deprecated/schema properties are detected from deprecated, function-style rules (@bmish)
• #355 Improve type for configEmoji option (@bmish)

:house: Internal

• #364 Refactor functions for generating and splitting the rules list (@bmish)
• #356 Refactor how rules are passed around in codebase (@bmish)
• #352 Better normalize pathRuleList option internally (@bmish)

Committers: 1

• Bryan Mishkin (@bmish)