docs: use eslint-doc-generator for rule documentation

[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 #1226 (and thanks @G-Rath and @SimenB for helping to inspire it). eslint-doc-generator is significantly more robust compared to the previous documentation generator script/tests which I have now removed. It has much more 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. Most 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.

Some differences include:

• The all config is hidden everywhere as a result of the --ignore-config all option
• Removed the ### Default configuration section header from some rule docs which was confusing because it was used for rules with no config/options (and causes the options section check to fail)

[G-Rath]

This sounds really cool! I'll have a proper look when I've got some time, but two initial thoughts:

• would it be possible to support having a different table for the type based rules? the reason I did that originally is because it seemed distracting to have a whole other column for something that only applies for one rule, and that we're probably not going to see any more type-based rules anytime soon (I expect that's probably true for a lot of plugins outside of @typescript-eslint)
• it looks like the script entry in package.json is pretty large - maybe it would make sense to have a lightweight config json file?

[bmish]

@G-Rath yes, I am planning to support both of those, see these issues:

• Add option to split rule list by meta.docs.category or potentially other criteria bmish/eslint-doc-generator#22
• Allow configuration in config file or package.json object bmish/eslint-doc-generator#95

[SimenB]

yay, this is awesome! stoked to see this land when Gareth is happy 🙂

[SimenB]

Hmm, weird CI failure needs to be investigated

[bmish]

I implemented a feature to separate the type-checking rules list with --split-by meta.docs.requiresTypeChecking and then was able to hide the type-checking column from the lists using the --rule-list-columns option.

Still need to investigate the CI failure.

[bmish]

The CI failure has been fixed by ensuring we build before running the generator.

This PR is ready for review.

Note that I plan to implement this feature eventually but would prefer not to block the PR on it:

• Allow configuration in config file or package.json object bmish/eslint-doc-generator#95

[bmish]

Just a heads up that this PR is still ready. I'm just updating it whenever I publish a new version of the tool.

[G-Rath]

sweet - I'll try and have a look over the weekend; thanks again for your work on this!

[G-Rath]

Great stuff! I have some mild feelings about if we really need so many columns in the table (i.e. the "Warn" and "fix vs suggest" specifically), but other maintainers don't seem mind and hey this is exactly what I was hoping for in the long run with my regenerate-docs script 😂

[bmish]

I have some mild feelings about if we really need so many columns in the table (i.e. the "Warn" and "fix vs suggest" specifically)

The good news is that the columns are configurable. I filed an issue to consider a consolidated column for fixable/suggestions: bmish/eslint-doc-generator#207.

For the configuration columns, I've gone through multiple iterations of it and the current design of a separate column per configured rule severity is by far the most scalable and robust solution I've reached. I didn't find a good way to represent different severities in a single config column.