Automatically generate ESLint plugin documentation from rule metadata and test cases.
npm install eslint-docgen --save-devReplace 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.
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:
Used as the description of the rule in the documentation.
Used to show a deprecation warning in the documentation, optionally with links to replacement rule(s).
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
}To migrate an existing plugin with manually built documentation you can use the following process:
- Follow the steps in Installation and Setup.
- Move your existing documentation to a new folder, e.g.
docs/template/MYRULE.mdand in your.eslintdocgenrcsetruleTemplatePathto this new folder, e.g."docs/template/{name}.md". Optionally you can rename these files to.ejs. - Run the generator (as described in Usage) to confirm that it copies your old documentation (now your templates) back to the original documentation path.
- Start switching out manually written sections of your templates with include blocks such as those found in
index.ejs.
Configuration for all rules in a project is controlled by creating a JSON/JavaScript file called .eslintdocgenrc.json/.eslintdocgenrc.js in your project root:
{
"docPath": "docs/rules/{name}.md",
// ...
}module.exports = {
docPath: 'docs/rules/{name}.md',
// ...
};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.
The following config options are available:
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".
The path where the rule is defined, only required if ruleLink is true. Same format as docPath.
The path where the rule's tests are defined, only required if testPath is true. Same format as docPath.
When defined, will try to use a rule specific template instead of index.ejs, e.g. "docs/templates/{name}.ejs". Same format as docPath.
When defined, templates in this path will override the global templates defined in src/templates.
Add a link to the documentation source in the "Resources" section.
Add a link to the rule source in the "Resources" section. Requires rulePath to be defined.
Add a link to the rule's test source in the "Resources" section. Requires testPath to be defined.
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.
Fix code examples using the ESLint configuration used for your main script.
Shows config comments at the top of code examples:
/* eslint myPlugin/rule: "error" */
// Test casesShow examples of how code is fixed by the rule.
Show the relevant file name for test cases.
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.
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.
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.
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.
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 } ]
}
}