From cc41715e5c5a1fd06424f177a8fb5488487675bc Mon Sep 17 00:00:00 2001
From: Phil Pirozhkov <pirjsuka@gmail.com>
Date: Tue, 3 Nov 2020 22:42:29 +0300
Subject: [PATCH] fixup! Add RSpec DSL configuration docs

---
 docs/modules/ROOT/pages/usage.adoc | 53 ++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/docs/modules/ROOT/pages/usage.adoc b/docs/modules/ROOT/pages/usage.adoc
index b6bd2e51e..c6eff6ef9 100644
--- a/docs/modules/ROOT/pages/usage.adoc
+++ b/docs/modules/ROOT/pages/usage.adoc
@@ -22,6 +22,59 @@ require:
 Now you can run `rubocop` and it will automatically load the RuboCop RSpec
 cops together with the standard cops.
 
+=== RSpec DSL configuration
+
+In case you https://github.com/rspec/rspec-core/blob/b0d0843a285693c64cdbe0c85726db155b46047e/lib/rspec/core/configuration.rb#L1122[define aliases for RSpec DSL], i.e. examples, example groups, hooks, or include example statements, you need to properly configure it so those elements are properly detected by RuboCop-RSpec.
+
+[source,ruby]
+----
+# spec/spec_helper.rb
+alias_example_group_to
+RSpec.configure do |c|
+  c.alias_example_group_to :detail, :detailed => true
+end
+
+# spec/detail_spec.rb
+RSpec.detail "a detail" do
+  it "can do some less important stuff" do
+  end
+end
+----
+
+[source,yaml]
+----
+# .rubocop.yml
+RSpec:
+  Language:
+    ExampleGroups:
+      Regular:
+        - detail
+----
+
+Some libraries extensively define RSpec DSL aliases (e.g. Pundit, ActionPolicy) or augment existing elements providing the same semantics (e.g. `let_it_be` from `test-prof`)
+Those libraries can provide necessary configuration, but won't necessarily do so.
+If they do, their README will mention that you have to explicitly require their configuration from your `.rubocop.yml` file.
+
+[source,yaml]
+----
+# .rubocop.yml
+
+require:
+ - rubocop-rspec
+ - test-prof
+
+# or
+
+RSpec:
+  Language:
+    Helpers:
+      - let_it_be
+----
+
+NOTE: the default merge mode is to inherit, so you won't remove any of the default settings.
+
+RuboCop-RSpec's https://github.com/rubocop-hq/rubocop-rspec/blob/a43424527c09fae2e6ddb133f4b2988f6c46bb2e/config/default.yml#L6[default configuration] is a good source of information on what can be configured.
+
 == Command line
 
 [source,bash]