Have individual documentation pages for each rule

[jfmengels]

Hi all!

I'm a maintainer of eslint-rule-documentation which is a tool that associates ESLint plugin rule names to the url of the rule's documentation page. This allows other tools (Atom's ESLint linter, Atom's XO linter, eslint-find-rules) to link to it easily, in linting errors for instance. This allows users to find the documentation page for a rule and read it to better understand why the error has been reported or learn how to configure it more to their needs.

In this example, import/no-extraneous-dependencies is a link that redirects to https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-extraneous-dependencies.md.

To provide a better experience to the users, eslint-rule-documentation should in my opinion link to an individual documentation page, where the rule is described in a bit of detail (reasoning, how it works, valid and invalid examples, when not to use it...). That is the case for ESLint core rules, and for many ESLint plugins. It is unfortunately not the case of this plugin, and would therefore request that you consider making this change. The standard way of doing things (advocated by the ESLint team) is to have individual markdown files located at docs/rules/<rulename>.md.

In the case of the rules copying and improving the behavior of core ESLint rules, I would recommend a simple file that would link to the original rule and describe why it should be used instead of the core ESLint rule.
For custom rules, something that looks like this or that would be awesome.

We have to manually add support for each ESLint plugin in eslint-rule-documentation to create links correctly (see what it looks like), and would prefer waiting to add support for this plugin until you have either refused, or agreed and implemented the change. I could provide help for this, but I would only do the grunt work, as I'm not accustomed to the rules to be able to explain the rationale for each.

Thank you for considering this, and of course, thank you all for your hard work on Babel and the plugin, they're awesome!

[hzoo]

The idea for the repo was a hack since we just replace the eslint rule at a point in time so didn't really think about documentation at the time. I'm in favor of doing it, but would ask for some help in adding it though.

In the case of the rules copying and improving the behavior of core ESLint rules, I would recommend a simple file that would link to the original rule and describe why it should be used instead of the core ESLint rule.

That sounds good because it would be the same thing except to account for some other case.

[jfmengels]

I'm in favor of doing it, but would ask for some help in adding it though

I can provide guidance and/or do the grunt work if you want. Just let me know. For the rationale behind the rules, I would then let you fill the gaps.

[kaicataldo]

Thank you for the issue. Now that @babel/eslint-plugin has been released, we are making this repository read-only. If this is a change you would still like to advocate for, please reopen this in the babel/babel monorepo.