automated changes from "rake docs:scrape"

Author: milesstanfield

config/contents/bundler/duplicated_gem.md

@@ -1,4 +1,5 @@
 A Gem's requirements should be listed only once in a Gemfile.
+
 ### Example:
     # bad
     gem 'rubocop'

config/contents/bundler/duplicated_group.md

@@ -0,0 +1,51 @@
+A Gem group, or a set of groups, should be listed only once in a Gemfile.
+
+For example, if the values of `source`, `git`, `platforms`, or `path`
+surrounding `group` are different, no offense will be registered:
+
+[source,ruby]
+-----
+platforms :ruby do
+    group :default do
+      gem 'openssl'
+    end
+end
+
+platforms :jruby do
+    group :default do
+      gem 'jruby-openssl'
+    end
+end
+-----
+
+### Example:
+    # bad
+    group :development do
+      gem 'rubocop'
+    end
+
+    group :development do
+      gem 'rubocop-rails'
+    end
+
+    # bad (same set of groups declared twice)
+    group :development, :test do
+      gem 'rubocop'
+    end
+
+    group :test, :development do
+      gem 'rspec'
+    end
+
+    # good
+    group :development do
+      gem 'rubocop'
+    end
+
+    group :development, :test do
+      gem 'rspec'
+    end
+
+    # good
+    gem 'rubocop', groups: [:development, :test]
+    gem 'rspec', groups: [:development, :test]

config/contents/bundler/gem_filename.md

@@ -0,0 +1,22 @@
+Verifies that a project contains Gemfile or gems.rb file and correct
+associated lock file based on the configuration.
+
+### Example: EnforcedStyle: Gemfile (default)
+    # bad
+    Project contains gems.rb and gems.locked files
+
+    # bad
+    Project contains Gemfile and gems.locked file
+
+    # good
+    Project contains Gemfile and Gemfile.lock
+
+### Example: EnforcedStyle: gems.rb
+    # bad
+    Project contains Gemfile and Gemfile.lock files
+
+    # bad
+    Project contains gems.rb and Gemfile.lock file
+
+    # good
+    Project contains gems.rb and gems.locked files

config/contents/bundler/insecure_protocol_source.md

@@ -1,15 +1,18 @@
-The symbol argument `:gemcutter`, `:rubygems`, and `:rubyforge`
-are deprecated. So please change your source to URL string that
-'https://rubygems.org' if possible, or 'http://rubygems.org' if not.
+Passing symbol arguments to `source` (e.g. `source :rubygems`) is
+deprecated because they default to using HTTP requests. Instead, specify
+`'https://rubygems.org'` if possible, or `'http://rubygems.org'` if not.
 
-This autocorrect will replace these symbols with 'https://rubygems.org'.
-Because it is secure, HTTPS request is strongly recommended. And in
-most use cases HTTPS will be fine.
+When autocorrecting, this cop will replace symbol arguments with
+`'https://rubygems.org'`.
 
-However, it don't replace all `sources` of `http://` with `https://`.
-For example, when specifying an internal gem server using HTTP on the
-intranet, a use case where HTTPS cannot be specified was considered.
-Consider using HTTP only if you cannot use HTTPS.
+This cop will not replace existing sources that use `http://`. This may
+be necessary where HTTPS is not available. For example, where using an
+internal gem server via an intranet, or where HTTPS is prohibited.
+However, you should strongly prefer `https://` where possible, as it is
+more secure.
+
+If you don't allow `http://`, please set `false` to `AllowHttpProtocol`.
+This option is `true` by default for safe autocorrection.
 
 ### Example:
     # bad
@@ -19,4 +22,13 @@ Consider using HTTP only if you cannot use HTTPS.
 
     # good
     source 'https://rubygems.org' # strongly recommended
-    source 'http://rubygems.org'
+
+### Example: AllowHttpProtocol: true (default)
+
+    # good
+    source 'http://rubygems.org' # use only if HTTPS is unavailable
+
+### Example: AllowHttpProtocol: false
+
+    # bad
+    source 'http://rubygems.org'

config/contents/bundler/ordered_gems.md

@@ -14,7 +14,15 @@ Gems should be alphabetically sorted within groups.
 
     gem 'rspec'
 
-    # good only if TreatCommentsAsGroupSeparators is true
+### Example: TreatCommentsAsGroupSeparators: true (default)
+    # good
+    # For code quality
+    gem 'rubocop'
+    # For tests
+    gem 'rspec'
+
+### Example: TreatCommentsAsGroupSeparators: false
+    # bad
     # For code quality
     gem 'rubocop'
     # For tests

config/contents/gemspec/date_assignment.md

@@ -0,0 +1,46 @@
+Enforce that gem dependency version specifications or a commit reference (branch,
+ref, or tag) are either required or forbidden.
+
+### Example: EnforcedStyle: required (default)
+
+    # bad
+    Gem::Specification.new do |spec|
+      spec.add_dependency 'parser'
+    end
+
+    # bad
+    Gem::Specification.new do |spec|
+      spec.add_development_dependency 'parser'
+    end
+
+    # good
+    Gem::Specification.new do |spec|
+      spec.add_dependency 'parser', '>= 2.3.3.1', '< 3.0'
+    end
+
+    # good
+    Gem::Specification.new do |spec|
+      spec.add_development_dependency 'parser', '>= 2.3.3.1', '< 3.0'
+    end
+
+### Example: EnforcedStyle: forbidden
+
+    # bad
+    Gem::Specification.new do |spec|
+      spec.add_dependency 'parser', '>= 2.3.3.1', '< 3.0'
+    end
+
+    # bad
+    Gem::Specification.new do |spec|
+      spec.add_development_dependency 'parser', '>= 2.3.3.1', '< 3.0'
+    end
+
+    # good
+    Gem::Specification.new do |spec|
+      spec.add_dependency 'parser'
+    end
+
+    # good
+    Gem::Specification.new do |spec|
+      spec.add_development_dependency 'parser'
+    end

config/contents/gemspec/dependency_version.md

@@ -0,0 +1,21 @@
+Checks that deprecated attributes are not set in a gemspec file.
+Removing deprecated attributes allows the user to receive smaller packed gems.
+
+### Example:
+
+    # bad
+    Gem::Specification.new do |spec|
+      spec.name = 'your_cool_gem_name'
+      spec.test_files = Dir.glob('test/**/*')
+    end
+
+    # bad
+    Gem::Specification.new do |spec|
+      spec.name = 'your_cool_gem_name'
+      spec.test_files += Dir.glob('test/**/*')
+    end
+
+    # good
+    Gem::Specification.new do |spec|
+      spec.name = 'your_cool_gem_name'
+    end

config/contents/gemspec/deprecated_attribute_assignment.md

@@ -0,0 +1,63 @@
+Enforce that development dependencies for a gem are specified in
+`Gemfile`, rather than in the `gemspec` using
+`add_development_dependency`. Alternatively, using `EnforcedStyle:
+gemspec`, enforce that all dependencies are specified in `gemspec`,
+rather than in `Gemfile`.
+
+### Example: EnforcedStyle: Gemfile (default)
+    # Specify runtime dependencies in your gemspec,
+    # but all other dependencies in your Gemfile.
+
+    # bad
+    # example.gemspec
+    s.add_development_dependency "foo"
+
+    # good
+    # Gemfile
+    gem "foo"
+
+    # good
+    # gems.rb
+    gem "foo"
+
+    # good (with AllowedGems: ["bar"])
+    # example.gemspec
+    s.add_development_dependency "bar"
+
+### Example: EnforcedStyle: gems.rb
+    # Specify runtime dependencies in your gemspec,
+    # but all other dependencies in your Gemfile.
+    #
+    # Identical to `EnforcedStyle: Gemfile`, but with a different error message.
+    # Rely on Bundler/GemFilename to enforce the use of `Gemfile` vs `gems.rb`.
+
+    # bad
+    # example.gemspec
+    s.add_development_dependency "foo"
+
+    # good
+    # Gemfile
+    gem "foo"
+
+    # good
+    # gems.rb
+    gem "foo"
+
+    # good (with AllowedGems: ["bar"])
+    # example.gemspec
+    s.add_development_dependency "bar"
+
+### Example: EnforcedStyle: gemspec
+    # Specify all dependencies in your gemspec.
+
+    # bad
+    # Gemfile
+    gem "foo"
+
+    # good
+    # example.gemspec
+    s.add_development_dependency "foo"
+
+    # good (with AllowedGems: ["bar"])
+    # Gemfile
+    gem "bar"

config/contents/gemspec/development_dependencies.md

@@ -40,7 +40,15 @@ Dependencies in the gemspec should be alphabetically sorted.
 
     spec.add_runtime_dependency 'rspec'
 
-    # good only if TreatCommentsAsGroupSeparators is true
+### Example: TreatCommentsAsGroupSeparators: true (default)
+    # good
+    # For code quality
+    spec.add_dependency 'rubocop'
+    # For tests
+    spec.add_dependency 'rspec'
+
+### Example: TreatCommentsAsGroupSeparators: false
+    # bad
     # For code quality
     spec.add_dependency 'rubocop'
     # For tests