docs: automate docs with eslint-doc-generator #504
Conversation
.eslint-doc-generatorrc.js
Outdated
| ignoreConfig: ['all', 'off'], | ||
| ruleDocSectionInclude: ['Rule Details'], | ||
| ruleListSplit: 'meta.docs.category', | ||
| postprocess: doc => format(doc, { parser: 'markdown' }), |
There was a problem hiding this comment.
We run the results through prettier to ensure formatting requirements are met.
| } | ||
| ``` | ||
|
|
||
| ## Options |
There was a problem hiding this comment.
Options sections are removed when a rule does not have options. This is part of the --rule-doc-section-options option.
| @@ -82,3 +88,7 @@ Because when assuming types, false positives may be found, it's recommended to s | |||
| ### `ignorePattern` | |||
|
|
|||
| See the [ignorePattern](./options/ignore-pattern.md) docs. | |||
|
|
|||
| ### `ignoreImmediateMutation` | |||
There was a problem hiding this comment.
This option was not mentioned. This is part of the --rule-doc-section-options option.
package.json
Outdated
| @@ -52,14 +52,16 @@ | |||
| "cz": "git-cz", | |||
| "format": "prettier --write \"./**/*.{md,ts}\"", | |||
| "prelint": "yarn build && yarn link && yarn link 'eslint-plugin-functional'", | |||
| "lint": "yarn lint-js && yarn lint-md", | |||
| "lint": "yarn lint-js && yarn lint-md && yarn lint-eslint-docs", | |||
| "lint-eslint-docs": "yarn update:eslint-docs --check", | |||
There was a problem hiding this comment.
Ensures the docs are kept up-to-date.
src/util/rule.ts
Outdated
| ESLintUtils.NamedCreateRuleMeta<T> & { | ||
| docs: { | ||
| /** Used for splitting the README rules list into sub-lists. */ | ||
| category: string; |
There was a problem hiding this comment.
Had to add this property to the rule meta object since we use it for splitting the rule lists. This is not an official ESLint property anymore but still commonly used by plugins.
README.md
Outdated
| [badge-no-object-orientation]: https://img.shields.io/badge/-no--object--orientation-yellow.svg | ||
| [badge-no-statements]: https://img.shields.io/badge/-no--statements-purple.svg | ||
| [badge-off]: https://img.shields.io/badge/-off-black.svg | ||
| [badge-stylistic]: https://img.shields.io/badge/-stylistic-gold.svg |
There was a problem hiding this comment.
We use badges to represent most configs. Alternatively, the tools allow an emoji to be specified for each config as desired.
|
This looks like a pretty cool tool. Would you be able to recreate this PR based of the |
|
@RebeccaStevens do you have any ETA on v5? If not too long, I might just wait until it gets merged to master to let things settle down first. |
|
Well, it was supposed to go out a few months back but it's kept being pushed back. |
|
@bmish I believe update 5 is done now. It should be release within the next week (assuming no issues are found before then). |
|
Still seems like it would be easier for me to just wait until v5 is merged to |
|
I believe all conflicts are now resolved and |
|
Okay targeting |
bmish
force-pushed
the
eslint-doc-generator
branch
2 times, most recently
from
829dd6f
to
870be6f
Compare
bmish
force-pushed
the
eslint-doc-generator
branch
from
870be6f
to
2656d28
Compare
|
@RebeccaStevens I recreated this entire PR against One note is I had to rename some rule docs which did not match their rule names. |
Thanks, I realized that issue and was going to fix it but I guess I don't need to now :) |
Codecov Report
@@ Coverage Diff @@
## next #504 +/- ##
=======================================
Coverage 90.32% 90.32%
=======================================
Files 46 46
Lines 1209 1209
Branches 318 318
=======================================
Hits 1092 1092
Misses 50 50
Partials 67 67
Flags with carried forward coverage won't be shown. Click here to find out more.
📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more |
eslint-doc-generator is a CLI tool I built for automating the generation of the README rules list table and rule doc title/notices for ESLint plugins. It follows common documentation conventions from this and other top ESLint plugins and will help us standardize documentation across ESLint plugins (and generally improve the usability of custom rules through better documentation and streamline the process of adding new rules). It has 100% test coverage and is used in many of the top ESLint plugins already.
The organization and representation of rules and configs in the README rules list is different from what you had before. See what you think.