eslint-docgen

eslint-docgen

Automatically generate ESLint plugin documentation from rule metadata and test cases.

⬇️ Installation

npm install eslint-docgen --save-dev

🛠️ Setup

Replace all uses of RuleTester with the version from this package:

// Old:
const RuleTester = require( 'eslint' ).RuleTester;
// New:
const RuleTester = require( 'eslint-docgen' ).RuleTester;

Create a configuration file as described in Configuration, setting docPath and preferably rulePath and testPath.

📖 Usage

To build your documentation, run your rule tests with the DOCGEN environment variable set in the command line, e.g.

DOCGEN=1 mocha tests/rules/

You could add this to your package.json to make it available as npm run doc, e.g.

{
    //
    "scripts": {
        //
        "doc": "rm -rf docs/rules && DOCGEN=1 mochan tests/rules/"
    }
    //
}

Documentation will be built using rule metadata and test data passed to RuleTester:

rule.meta.docs.description

Used as the description of the rule in the documentation.

rule.meta.docs.deprecated / rule.meta.docs.replacedBy

Used to show a deprecation warning in the documentation, optionally with links to replacement rule(s).

tests.valid/tests.invalid from RuleTester#run

Will generate code blocks showing examples of valid/invalid usage. Blocks will be grouped by unique options/settings configurations. Fixable rules with output will generate a separate block showing the before and after.

By default all test cases will be included in the examples. To exclude specific test cases from these code blocks use the docgen: false option:

{
    code: 'App.method();',
    docgen: false
}

If you have excludeExamplesByDefault set to true in your config, you can include specific test cases in these code blocks by using the docgen: true option:

{
    code: 'App.method();',
    docgen: true
}

🤖 Migration

To migrate an existing plugin with manually built documentation you can use the following process:

1. Follow the steps in Installation and Setup.
2. Move your existing documentation to a new folder, e.g. docs/template/MYRULE.md and in your .eslintdocgenrc set ruleTemplatePath to this new folder, e.g. "docs/template/{name}.md". Optionally you can rename these files to .ejs.
3. Run the generator (as described in Usage) to confirm that it copies your old documentation (now your templates) back to the original documentation path.
4. Start switching out manually written sections of your templates with include blocks such as those found in index.ejs.

⚙️ Configuration

Configuration for all rules in a project is controlled by creating a JSON/JavaScript file called .eslintdocgenrc.json/.eslintdocgenrc.js in your project root:

JSON

{
    "docPath": "docs/rules/{name}.md",
    // ...
}

JavaScript

module.exports = {
    docPath: 'docs/rules/{name}.md',
    // ...
};

Overriding

The project-wide rules configuration can be overridden for individual rules by adding a docgenConfig property to the tests object passed to RuleTester.run(). All configuration options that are supported project-wide can be changed.

Options

The following config options are available:

docPath (required)

The path to store rule documentation files, with {name} as a placeholder for the rule name, e.g. "docs/rules/{name}.md" or "rules/{name}/README.md".

rulePath

The path where the rule is defined, only required if ruleLink is true. Same format as docPath.

testPath

The path where the rule's tests are defined, only required if testPath is true. Same format as docPath.

ruleTemplatePath

When defined, will try to use a rule specific template instead of index.ejs, e.g. "docs/templates/{name}.ejs". Same format as docPath.

globalTemplatePath

When defined, templates in this path will override the global templates defined in src/templates.

docLink (default false)

Add a link to the documentation source in the "Resources" section.

ruleLink (default true)

Add a link to the rule source in the "Resources" section. Requires rulePath to be defined.

testLink (default true)

Add a link to the rule's test source in the "Resources" section. Requires testPath to be defined.

pluginName (default from package name)

The name of your plugin as used in directives, e.g. plugin:pluginName/rule. Defaults to the name in package.json with eslint-plugin- stripped.

fixCodeExamples (default true)

Fix code examples using the ESLint configuration used for your main script.

showConfigComments (default false)

Shows config comments at the top of code examples:

/* eslint myPlugin/rule: "error" */
// Test cases

showFixExamples (default true)

Show examples of how code is fixed by the rule.

showFilenames (default: false)

Show the relevant file name for test cases.

excludeExamplesByDefault (default false)

Exclude tests from being used as examples by default. When this is true users must set docgen: true on any test they want to be included in examples.

minExamples (default ['warn', 2])

Minimum examples per rule. Tuple where first value is one of 'warn' or 'error', and the second value is the minimum number of examples required. Use null for no minimum.

maxExamples (default ['warn', 50])

Maximum examples per rule. Tuple where first value is one of 'warn' or 'error', and the second value is the maximum number of examples allowed. Use null for no maximum.

tabWidth (default 4)

Number of spaces to convert tabs to in code examples. Tabs in examples are always converted to spaces so their widths can be determined reliably for alignment.

🔍 Rules index

To assist with building an index of your rules, for example to put in a root README, this package exports rulesWithConfig. The value is a Map much like the one returned by Linter#getRules but each rule has an additional configMap property that describes which configs include the rule and the options used (null if no options are used).

Note that the rule names do not include the plugin prefix.

Example:

require( 'eslint-docgen' ).rulesWithConfig.get( 'no-event-shorthand' );
// Outputs:
{
    meta: [Object],
    create: [Function],
    configMap: Map {
        'deprecated-3.5' => null,
        'deprecated-3.3' => [ { allowAjaxEvents: true } ]
    }
}

✏️ Examples

• Rule in eslint-plugin-no-jquery
• Rule in eslint-plugin-mediawiki
• Sample test case output