Merge pull request #913 from JonRowe/deprecation_io_docs

Document deprection_io with a feature
add a new DeprecationFormatter to print deprecations (and summary)
warn_deprecation supports arbitrary custom messages again
internal: update add_formatter to support multiple streams

Supports treating the DeprecationFormatter like the others.
fix example failing in Ruby 1.8
fix false positive from previous commit
update deprecation stream cuke to match new API
no need to create a file in the formatter - happens already in configuration
remove unused method
change doc references to STDOUT to $stdout

[ci skip]
clean up the description in a cuke [ci skip]
RSpec.deprecate accepts a hash

It also continues to support separate args for now. That can be
removed after the other rspec gems have been updated.
rename alternate_method to replacement
push warn_deprecation through deprecate
rename :method key to :deprecated

Constants and usage can also be deprecated.
RSpec.deprecate(deprecated, options_hash)
whitespace
change :called_from to :call_site
uncomment commented code
it's me