Automate docs with eslint-doc-generator

[bmish]

I built this CLI tool eslint-doc-generator for automating the generation of the README rules list 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 our custom rules through better documentation and streamline the process of adding new rules).

This is a follow-up to the work I did to add the original notices in #1576. eslint-doc-generator is significantly more robust compared to the previous documentation generator script/tests which I have now removed. It has additional functionality (for example, the rules list legend is auto-generated, and the rules list will show additional columns of information when applicable) and 100% test coverage.

There are some discrepancies between the old docs and the new docs. Some of these are intentional and likely improvements. If you don't like any of the changes, let me know and I can tweak eslint-doc-generator or add a config option to support the desired behavior.

[fisker]

I slightly prefer to keep codes in scripts/, so we can tweak them anytime we want.

The only missing part is the rule title, it's easy to support, I planned to do that, but haven't got time.

[bmish]

I slightly prefer to keep codes in scripts/, so we can tweak them anytime we want.

It is true you can more-easily tweak the current in-house scripts. I'm hoping the benefits I described in the PR description will outweigh that downside, in addition to these selling points:

• I plan to move eslint-doc-generator to @eslint-community sometime after reaching v1
• eslint-doc-generator will be less likely to break vs. maintaining in-house scripts since it is fully unit tested, written in TypeScript, and will be adopted by / tested on many of the top ESLint plugins
• eslint-doc-generator will be increasingly-configurable so many desired tweaks will be possible simply through a config option

The only missing part is the rule title, it's easy to support, I planned to do that, but haven't got time.

What do you mean the "rule title" is missing?

[fisker]

What do you mean the "rule title" is missing?

I mean, currently, we are not auto-generating rule titles, but this PR did.

[fisker]

I'll leave the decision to Sindre.

[sindresorhus]

@bmish I think it may be smart to have a notice like this.

Maybe:

<!-- end rule header -->
<!-- DO NOT EDIT ANYTHING ABOVE HERE -->

[bmish]

I added those original warning comments back in. But they aren't managed by eslint-doc-generator as they are outside the managed area indicated by the <!-- end rule header --> comment.

[bmish]

Filed an issue to consider making this part of the standard comment marker: bmish/eslint-doc-generator#150

[sindresorhus]

I'm a big 👍 on this. I hope all ESLint plugins adopt this so we can get some universal consistency.

[sindresorhus]

You need to ensure the rule names have more space so less of them are word wrapped. See the difference between our and yours:

• https://github.com/sindresorhus/eslint-plugin-unicorn#rules
• https://github.com/sindresorhus/eslint-plugin-unicorn/blob/68a674c09162e8dac934be3c3e9bcfb018158143/readme.md#rules

[sindresorhus]

Can you apply --rule-doc-section-include for the Fail and Pass sections?

[sindresorhus]

Would be nice if you could define the config in package.json instead of as CLI flags.

https://github.com/sindresorhus/pkg-conf or a similar package.

[sindresorhus]

The docs for --rule-doc-title-format should have an example for each style.

https://github.com/bmish/eslint-doc-generator#configuration-options

[bmish]

Thanks for the feedback! Will work on making the tweaks and responding in the next few days.

[bmish]

The docs for --rule-doc-title-format should have an example for each style.

bmish/eslint-doc-generator#configuration-options

Done. See: https://github.com/bmish/eslint-doc-generator#--rule-doc-title-format

Would be nice if you could define the config in package.json instead of as CLI flags.

sindresorhus/pkg-conf or a similar package.

Planned in bmish/eslint-doc-generator#95.

Can you apply --rule-doc-section-include for the Fail and Pass sections?

I wanted to use this but there isn't (yet) any way to opt out rules from that check which we need because of:

eslint-plugin-unicorn/test/package.mjs

Line 63 in dd92f06

const RULES_WITHOUT_PASS_FAIL_SECTIONS = new Set([

You need to ensure the rule names have more space so less of them are word wrapped. See the difference between our and yours:

• sindresorhus/eslint-plugin-unicorn#rules
• 68a674c/readme.md#rules

Fixed in bmish/eslint-doc-generator#148.

Also implemented a consolidated fixable/suggestions notice: bmish/eslint-doc-generator#149.

@sindresorhus all the critical feedback so far should be addressed. Please keep the feedback coming and let me know if you see any blockers.

[fisker]

One comment. #1930 (comment)