{"id":13801991,"url":"https://github.com/wikimedia/eslint-docgen","last_synced_at":"2026-02-12T23:31:59.500Z","repository":{"id":43741501,"uuid":"263679441","full_name":"wikimedia/eslint-docgen","owner":"wikimedia","description":"Automatically generate ESLint plugin documentation from rule metadata and test cases.","archived":false,"fork":false,"pushed_at":"2024-05-16T18:55:47.000Z","size":715,"stargazers_count":11,"open_issues_count":13,"forks_count":8,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-09-09T18:16:15.603Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wikimedia.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-13T16:07:11.000Z","updated_at":"2025-07-12T17:37:30.000Z","dependencies_parsed_at":"2024-01-08T10:16:37.582Z","dependency_job_id":"2be8efb9-1006-4259-b059-47ebc065835b","html_url":"https://github.com/wikimedia/eslint-docgen","commit_stats":{"total_commits":130,"total_committers":5,"mean_commits":26.0,"dds":0.0692307692307692,"last_synced_commit":"ecff3e4f9bf48da27bcce1dddebe7bb2c2e9f1a1"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/wikimedia/eslint-docgen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikimedia%2Feslint-docgen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikimedia%2Feslint-docgen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikimedia%2Feslint-docgen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikimedia%2Feslint-docgen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wikimedia","download_url":"https://codeload.github.com/wikimedia/eslint-docgen/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikimedia%2Feslint-docgen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29386217,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T22:07:52.078Z","status":"ssl_error","status_checked_at":"2026-02-12T22:07:49.026Z","response_time":55,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T00:01:32.462Z","updated_at":"2026-02-12T23:31:59.482Z","avatar_url":"https://github.com/wikimedia.png","language":"JavaScript","funding_links":[],"categories":["Developing for ESLint"],"sub_categories":["Testing Tools"],"readme":"# eslint-docgen\nAutomatically generate ESLint plugin documentation from rule metadata and test cases.\n\n## ⬇️ Installation\n\n```sh\nnpm install eslint-docgen --save-dev\n```\n\n## 🛠️ Setup\n\nReplace all uses of `RuleTester` with the version from this package:\n```js\n// Old:\nconst RuleTester = require( 'eslint' ).RuleTester;\n// New:\nconst RuleTester = require( 'eslint-docgen' ).RuleTester;\n```\n\nCreate a configuration file as described in [*Configuration*](#%EF%B8%8F-configuration), setting `docPath` and preferably `rulePath` and `testPath`.\n\n## 📖 Usage\nTo build your documentation, run your rule tests with the `DOCGEN` environment variable set in the command line, e.g.\n```sh\nDOCGEN=1 mocha tests/rules/\n```\n\nYou could add this to your package.json to make it available as `npm run doc`, e.g.\n```jsonc\n{\n    //\n    \"scripts\": {\n        //\n        \"doc\": \"rm -rf docs/rules \u0026\u0026 DOCGEN=1 mochan tests/rules/\"\n    }\n    //\n}\n```\n\nDocumentation will be built using **rule metadata** and **test data** passed to `RuleTester`:\n\n#### `rule.meta.docs.description`\nUsed as the description of the rule in the documentation.\n\n#### `rule.meta.docs.deprecated` / `rule.meta.docs.replacedBy`\nUsed to show a deprecation warning in the documentation, optionally with links to replacement rule(s).\n\n#### `tests.valid`/`tests.invalid` from `RuleTester#run`\nWill 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.\n\nBy default all test cases will be included in the examples. To **exclude** specific test cases from these code blocks use the `docgen: false` option:\n```js\n{\n    code: 'App.method();',\n    docgen: false\n}\n```\n\nIf 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:\n```js\n{\n    code: 'App.method();',\n    docgen: true\n}\n```\n\n\n## 🤖 Migration\nTo migrate an existing plugin with manually built documentation you can use the following process:\n\n1. Follow the steps in [*Installation*](#%EF%B8%8F-installation) and [*Setup*](#%EF%B8%8F-setup).\n2. 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`.\n3. Run the generator (as described in [*Usage*](#-usage)) to confirm that it copies your old documentation (now your templates) back to the original documentation path.\n4. Start switching out manually written sections of your templates with include blocks such as those found in [`index.ejs`](src/templates/index.ejs).\n\n## ⚙️ Configuration\n\nConfiguration for all rules in a project is controlled by creating a JSON/JavaScript file called `.eslintdocgenrc.json`/`.eslintdocgenrc.js` in your project root:\n\n#### JSON\n```jsonc\n{\n    \"docPath\": \"docs/rules/{name}.md\",\n    // ...\n}\n```\n\n#### JavaScript\n```js\nmodule.exports = {\n    docPath: 'docs/rules/{name}.md',\n    // ...\n};\n```\n\n#### Overriding\n\nThe 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.\n\n### Options\n\nThe following config options are available:\n\n#### `docPath` (*required*)\nThe 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\"`.\n\n#### `rulePath`\nThe path where the rule is defined, only required if `ruleLink` is `true`. Same format as `docPath`.\n\n#### `testPath`\nThe path where the rule's tests are defined, only required if `testPath` is `true`. Same format as `docPath`.\n\n#### `ruleTemplatePath`\nWhen defined, will try to use a rule specific template instead of [`index.ejs`](src/templates/index.ejs), e.g. `\"docs/templates/{name}.ejs\"`. Same format as `docPath`.\n\n#### `globalTemplatePath`\nWhen defined, templates in this path will override the global templates defined in [`src/templates`](src/templates).\n\n#### `docLink` (default `false`)\nAdd a link to the documentation source in the \"Resources\" section.\n\n#### `ruleLink` (default `true`)\nAdd a link to the rule source in the \"Resources\" section. Requires `rulePath` to be defined.\n\n#### `testLink` (default `true`)\nAdd a link to the rule's test source in the \"Resources\" section. Requires `testPath` to be defined.\n\n#### `pluginName` (default from package name)\nThe name of your plugin as used in directives, e.g. `plugin:pluginName/rule`. Defaults to the name in `package.json` with `eslint-plugin-` stripped.\n\n#### `fixCodeExamples` (default `true`)\nFix code examples using the ESLint configuration used for your `main` script.\n\n#### `showConfigComments` (default `false`)\nShows config comments at the top of code examples:\n```js\n/* eslint myPlugin/rule: \"error\" */\n// Test cases\n```\n\n#### `showFixExamples` (default `true`)\nShow examples of how code is fixed by the rule.\n\n#### `showFilenames` (default: `false`)\nShow the relevant file name for test cases.\n\n#### `excludeExamplesByDefault` (default `false`)\nExclude 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.\n\n#### `minExamples` (default `['warn', 2]`)\nMinimum 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.\n\n#### `maxExamples` (default `['warn', 50]`)\nMaximum 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.\n\n#### `tabWidth` (default `4`)\nNumber 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.\n\n## 🔍 Rules index\n\nTo 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](https://eslint.org/docs/developer-guide/nodejs-api#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).\n\nNote that the rule names do not include the plugin prefix.\n\nExample:\n```js\nrequire( 'eslint-docgen' ).rulesWithConfig.get( 'no-event-shorthand' );\n// Outputs:\n{\n    meta: [Object],\n    create: [Function],\n    configMap: Map {\n        'deprecated-3.5' =\u003e null,\n        'deprecated-3.3' =\u003e [ { allowAjaxEvents: true } ]\n    }\n}\n```\n\n## ✏️ Examples\n* [Rule in eslint-plugin-no-jquery](https://github.com/wikimedia/eslint-plugin-no-jquery/blob/master/docs/rules/no-error-shorthand.md)\n* [Rule in eslint-plugin-mediawiki](https://github.com/wikimedia/eslint-plugin-mediawiki/blob/master/docs/rules/valid-package-file-require.md)\n* [Sample test case output](tests/cases/simple-rule.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwikimedia%2Feslint-docgen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwikimedia%2Feslint-docgen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwikimedia%2Feslint-docgen/lists"}