Teach brew style about docs/.rubocop.yml

- Yes, we have yet another `.rubocop.yml` but in-line exclusions in
  `<span class="display:none;">` in the Markdown seemed more ugly.
- This needed tweaks to `brew style` to make it read the new config
  file when we're scanning docs.

.github/workflows/docs.yml

@@ -42,7 +42,7 @@ jobs:
 
       - name: Check code blocks conform to our Ruby style guide
         working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs
-        run: brew style -- *.md
+        run: brew style .
 
       - name: Build the site and check for broken links
         working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs

Library/Homebrew/style.rb

@@ -126,6 +126,8 @@ def self.run_rubocop(files, output_type,
       files&.map!(&:expand_path)
       if files.blank? || files == [HOMEBREW_REPOSITORY]
         files = [HOMEBREW_LIBRARY_PATH]
+      elsif files.any? { |f| f.to_s.start_with? HOMEBREW_REPOSITORY/"docs" }
+        args << "--config" << (HOMEBREW_REPOSITORY/"docs/.rubocop.yml")
       elsif files.none? { |f| f.to_s.start_with? HOMEBREW_LIBRARY_PATH }
         args << "--config" << (HOMEBREW_LIBRARY/".rubocop.yml")
       end

docs/.rubocop.yml

@@ -0,0 +1,25 @@
+inherit_from: ../Library/.rubocop.yml
+
+AllCops:
+  Exclude:
+  - Gemfile
+  - ".mdl*.rb"
+  - Rakefile
+  - "_site/**/*"
+
+# These are included in docs deliberately to show what
+# `brew create` does and what the user should replace.
+FormulaAudit/Comments:
+  Enabled: false
+
+# The bottle block line length is long in its full form.
+Layout/LineLength:
+  Max: 123
+
+# Apparently Casks are allowed to have constant definitions in blocks and we document this.
+Lint/ConstantDefinitionInBlock:
+  Enabled: false
+
+# A fake regexp is deliberately documented for `inreplace` in the Formula Cookbook.
+Style/RedundantRegexpArgument:
+  Enabled: false

docs/Formula-Cookbook.md

@@ -495,7 +495,7 @@ inreplace "path", before, after
 
 ```ruby
 inreplace "path" do |s|
-  s.gsub!("foo", "bar")
+  s.gsub!(/foo/, "bar")
   s.gsub! "123", "456"
 end
 ```