Rubocop: Improve the manual

[bbatsov]

Some of you might have noticed that our long README was recently replaced by a manual (http://rubocop.readthedocs.io/en/latest/). This was just the first step, however, as the content of the manual was simply lifted from the README and rearranged a bit. To get where I want us to be we need to:

• improve the prose a lot (which is related to extending many of the existing sections with additional explanations and so on)
• add some listings of all the cops (e.g. as in http://www.foodcritic.io/#FC003)
• add sections on extending RuboCop
• add some FAQ/troubleshooting sections

I think this is one of the most important task for the project going forward and I'd love it if you could lend me a hand with it!

[connorshea]

SCSS Lint's list of linters is a really good example to base the cop listing off of: https://github.com/brigade/scss-lint/blob/master/lib/scss_lint/linter/README.md

[smackesey]

+1 on listings of all cops. I am new to RuboCop and just read through the manual and README. I was continually frustrated by the lack of a reference for all the standard cops. Eventually I discovered I could run $rubocop --show-cops.

[bbatsov]

PRs welcome. :-) Unfortunately I'm really short on time and won't be able to tackle this myself in the foreseeable future.

[Drenmi]

@bbatsov: Tangentially related. I have quite a bit of supporting material I created for myself to learn how to contribute to the codebase. Do we have something like a developer manual? If not, do we want one? If so, where do you think it should go? 😀

[bbatsov]

Just add a new section to the existing manual.

[sihu]

I created an index of all available cops and added the description and the URL to the StyleGuide, which you get by $rubocop --show-cops.. Now manual/cops.md is a really long file. What do you think about splitting it up:

• cops.md:
  
  
  
  • overview and description of the cop-types
  
  
  • index of all cops-titles with links to detailed information
  
  
• seperate file for each type eg. cops_style.md, cops_rails.md:
  
  
  
  • including description, examples for each type
  
  

Still open for the overview:

• examples for each case

[pocke]

Do we have something like a developer manual? If not, do we want one? If so, where do you think it should go?

I've added development.md in #3533 .
https://github.com/bbatsov/rubocop/blob/master/manual/development.md