Awesome
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:
- Follow the steps in Installation and Setup.
- Move your existing documentation to a new folder, e.g.
docs/template/MYRULE.md
and in your.eslintdocgenrc
setruleTemplatePath
to 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
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 } ]
}
}