Include linter rules on Dart.dev

[parlough]

The goal is to standardize hosting rule information on dart.dev similar to the analyzer diagnostics. As a result, the style followed implementing this followed closely to that.

Parker's must complete tasks:

• Add dart specifier to linter code blocks (Add a language label to the dart code blocks dart-archive/linter#2508)
• Actually write out an appropriate description of the linter
• Write descriptions for the types of rules
• Add explanations for the maturity levels
• Improve sidebar spacing and formatting so entire lint rule can be read (Improvements for long text in TOC #3089)
• Implement some GitHub action to indicate this needs to be updated (Add tool to check if diagnostic files are updated #3171)

Long term tasks for after landing:

• Flesh out each individual lint documentation, standardizing on a style similar to analyzer diagnostics
• Update other locations to refer to this link where appropriate
• Include rule set(s) in the listings in some fashion(need to iterate on designs). This will be important when the recommended rule sets are released.

You can find a staged version of this here:
Last updated 05-09-21
https://parlough-dart-dev.web.app/tools/linter-rules

[parlough]

@kwalrath @pq

This is ready for review.

At first, I don't plan to replace the external(analyzer) linkages to this page. The goal is to get this in a good state to merge, then I can incrementally work on the necessary improvements in smaller follow-up pull requests. This gives time to identify issues and will make reviewing easier.

[pq]

This looks great.

fyi @mit-mit as this bears on team-recommended lints.

@parlough: is the json a copy of what's in the linter gh-pages branch?

https://github.com/dart-lang/linter/blob/gh-pages/lints/machine/rules.json

What are your thoughts about keep that all synced up?

[parlough]

@pq Ah that's where the generated file is. I regenerated it manually since I forgot where I found it originally. I will keep it up synced up from there for now, but I'm wondering if we can create a GitHub action(on here or linter repo) with a cron job that checks if the file is updated and makes a commit or PR on this repository.

[pq]

Yeah, some auto-sync would be good. Not sure about automating commits -- never looked into it! Alternatively, you could add a check that just fails the build when they've gone out of sync? (Not as awesome but at least lets you know when things have gone stale...)

[parlough]

Rebased and staged at https://parlough-dart-dev.web.app/tools/linter-rules

[kwalrath]

I have a bunch of nitpicky word comments, but I love the way you've organized the page!

[kwalrath]

I don't understand why my review comments appeared in the order they did... but hopefully you can make sense of them.

[parlough]

@kwalrath Thanks for the thorough review and comments, I appreciate them a lot! I went through and included your changes as well as made some other minor adjustments. Please take another look when you get a chance :)

[kwalrath]

LGTM, but I have a question for @mit-mit that should be answered before we ship this page.

[kwalrath]

@mit-mit should we point to https://pub.dev/packages/lints instead?

[parlough]

I was planning on a follow-up change for once lints has a 1.0.0 version released documenting the different types as well to make all those changes easier to review, but I'd be happy to include them in this PR instead. Just let me know!

[kwalrath]

I say let's publish this now and file an issue reminding us to update the package!