Move some text from the README to the docs

Author: bbatsov

README.md

@@ -69,26 +69,6 @@ rubocop-rspec is available on Code Climate as part of the rubocop engine. [Learn
 
 You can read more about RuboCop-RSpec in its [official manual](https://docs.rubocop.org/rubocop-rspec).
 
-## Inspecting files that don't end with `_spec.rb`
-
-By default, `rubocop-rspec` only inspects code within paths ending in `_spec.rb` or including `spec/`. You can override this setting in your config file by specifying one or more patterns:
-
-```yaml
-# Inspect all files
-AllCops:
-  RSpec:
-    Patterns:
-    - '.+'
-```
-
-```yaml
-# Inspect only files ending with `_test.rb`
-AllCops:
-  RSpec:
-    Patterns:
-    - '_test.rb$'
-```
-
 ## The Cops
 
 All cops are located under
@@ -104,46 +84,6 @@ RSpec/FilePath:
     - spec/my_poorly_named_spec_file.rb
 ```
 
-## Non-goals of RuboCop RSpec
-
-### Enforcing `should` vs. `expect` syntax
-
-Enforcing
-
-```ruby
-expect(calculator.compute(line_item)).to eq(5)
-```
-
-over
-
-```ruby
-calculator.compute(line_item).should == 5
-```
-
-is a feature of RSpec itself – you can read about it in the [RSpec Documentation](https://relishapp.com/rspec/rspec-expectations/docs/syntax-configuration#disable-should-syntax)
-
-### Enforcing an explicit RSpec receiver for top-level methods (disabling monkey patching)
-
-Enforcing
-
-```ruby
-RSpec.describe MyClass do
-  ...
-end
-```
-
-over
-
-```ruby
-describe MyClass do
-  ...
-end
-```
-
-can be achieved using RSpec's `disable_monkey_patching!` method, which you can read more about in the [RSpec Documentation](https://relishapp.com/rspec/rspec-core/v/3-7/docs/configuration/zero-monkey-patching-mode#monkey-patched-methods-are-undefined-with-%60disable-monkey-patching!%60). This will also prevent `should` from being defined on every object in your system.
-
-Before disabling `should` you will need all your specs to use the `expect` syntax. You can use [Transpec](http://yujinakayama.me/transpec/), which will do the conversion for you.
-
 ## Contributing
 
 Checkout the [contribution guidelines](.github/CONTRIBUTING.md).

docs/modules/ROOT/pages/index.adoc

@@ -1,2 +1,53 @@
+= RuboCop RSpec
+
 RSpec-specific analysis for your projects, as an extension to
 https://github.com/rubocop-hq/rubocop[RuboCop].
+
+== Project Goals
+
+* Enforce the guidelines and best practices outlined in the community https://rspec.rubystyle.guide[RSpec style guide]
+* Simplify the process of adopting new RSpec functionality
+
+== Non-goals of RuboCop RSpec
+
+=== Enforcing `should` vs. `expect` syntax
+
+Enforcing
+
+[source,bash]
+----
+expect(calculator.compute(line_item)).to eq(5)
+----
+
+over
+
+[source,bash]
+----
+calculator.compute(line_item).should == 5
+----
+
+is a feature of RSpec itself – you can read about it in the https://relishapp.com/rspec/rspec-expectations/docs/syntax-configuration#disable-should-syntax[RSpec Documentation].
+
+=== Enforcing an explicit RSpec receiver for top-level methods (disabling monkey patching)
+
+Enforcing
+
+[source,bash]
+----
+RSpec.describe MyClass do
+  ...
+end
+----
+
+over
+
+[source,bash]
+----
+describe MyClass do
+  ...
+end
+----
+
+can be achieved using RSpec's `disable_monkey_patching!` method, which you can read more about in the https://relishapp.com/rspec/rspec-core/v/3-7/docs/configuration/zero-monkey-patching-mode#monkey-patched-methods-are-undefined-with-%60disable-monkey-patching!%60[RSpec Documentation]. This will also prevent `should` from being defined on every object in your system.
+
+Before disabling `should` you will need all your specs to use the `expect` syntax. You can use http://yujinakayama.me/transpec/[Transpec], which will do the conversion for you.

docs/modules/ROOT/pages/usage.adoc

@@ -18,7 +18,7 @@ cops together with the standard cops.
 
 [source,bash]
 ----
-rubocop --require rubocop-rspec
+$ rubocop --require rubocop-rspec
 ----
 
 == Rake task
@@ -33,3 +33,26 @@ end
 == Code Climate
 
 `rubocop-rspec` is available on Code Climate as part of the rubocop engine. https://codeclimate.com/changelog/55a433bbe30ba00852000fac[Learn More].
+
+== Inspecting files that don't end with `_spec.rb`
+
+By default, `rubocop-rspec` only inspects code within paths ending in `_spec.rb` or including `spec/`. You can override this setting in your config file by specifying one or more patterns:
+
+[source,yaml]
+----
+# Inspect all files
+AllCops:
+  RSpec:
+    Patterns:
+    - '.+'
+----
+
+
+[source,yaml]
+----
+# Inspect only files ending with `_test.rb`
+AllCops:
+  RSpec:
+    Patterns:
+    - '_test.rb$'
+----