From 9786955abec914f6a176ba4d8b29ea3b6a5f9194 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Sun, 21 Jan 2024 14:29:15 +0000
Subject: [PATCH 01/16] Add `rubocop-md` gem to the Gemfile in the style group

- This could be useful for linting code in our docs.
---
 Library/Homebrew/Gemfile      | 1 +
 Library/Homebrew/Gemfile.lock | 3 +++
 2 files changed, 4 insertions(+)

diff --git a/Library/Homebrew/Gemfile b/Library/Homebrew/Gemfile
index 02a9cc0900..8639977b78 100644
--- a/Library/Homebrew/Gemfile
+++ b/Library/Homebrew/Gemfile
@@ -42,6 +42,7 @@ group :pry, optional: true do
 end
 group :style, optional: true do
   gem "rubocop", require: false
+  gem "rubocop-md", require: false
   gem "rubocop-performance", require: false
   gem "rubocop-rails", require: false
   gem "rubocop-rspec", require: false
diff --git a/Library/Homebrew/Gemfile.lock b/Library/Homebrew/Gemfile.lock
index 9927f2026c..1079d9af9c 100644
--- a/Library/Homebrew/Gemfile.lock
+++ b/Library/Homebrew/Gemfile.lock
@@ -113,6 +113,8 @@ GEM
       rubocop (~> 1.41)
     rubocop-factory_bot (2.25.1)
       rubocop (~> 1.41)
+    rubocop-md (1.2.2)
+      rubocop (>= 1.0)
     rubocop-performance (1.20.2)
       rubocop (>= 1.48.1, < 2.0)
       rubocop-ast (>= 1.30.0, < 2.0)
@@ -209,6 +211,7 @@ DEPENDENCIES
   rspec_junit_formatter
   rubocop
   rubocop-ast
+  rubocop-md
   rubocop-performance
   rubocop-rails
   rubocop-rspec

From 7c25ea6e3ababf23ed4f91abf53c2f9798fda5b8 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Sun, 21 Jan 2024 14:30:28 +0000
Subject: [PATCH 02/16] Configure RuboCop to use `rubocop-md`

---
 Library/.rubocop.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Library/.rubocop.yml b/Library/.rubocop.yml
index 1fc717c0b5..31419cf7b2 100644
--- a/Library/.rubocop.yml
+++ b/Library/.rubocop.yml
@@ -1,6 +1,7 @@
 ---
 require:
   - ./Homebrew/rubocops.rb
+  - rubocop-md
   - rubocop-performance
   - rubocop-rails
   - rubocop-rspec

From e2251ad4be0b1287dfce206f3e309385e04000e1 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Sun, 21 Jan 2024 22:15:25 +0000
Subject: [PATCH 03/16] `brew vendor-gems` for `rubocop-md`

---
 Library/Homebrew/vendor/bundle/bundler/setup.rb | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Library/Homebrew/vendor/bundle/bundler/setup.rb b/Library/Homebrew/vendor/bundle/bundler/setup.rb
index 1e79e83abd..52e1cdaeac 100644
--- a/Library/Homebrew/vendor/bundle/bundler/setup.rb
+++ b/Library/Homebrew/vendor/bundle/bundler/setup.rb
@@ -101,6 +101,7 @@ $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version
 $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/rubocop-1.60.1/lib")
 $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/rubocop-capybara-2.20.0/lib")
 $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/rubocop-factory_bot-2.25.1/lib")
+$:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/rubocop-md-1.2.2/lib")
 $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/rubocop-performance-1.20.2/lib")
 $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/rubocop-rails-2.23.1/lib")
 $:.unshift File.expand_path("#{__dir__}/../#{RUBY_ENGINE}/#{Gem.ruby_api_version}/gems/rubocop-rspec-2.26.1/lib")

From 28c513ac9d0544616907b7b61bb50cc3253eaa53 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Sun, 21 Jan 2024 22:55:35 +0000
Subject: [PATCH 04/16] Fix basic Ruby syntax errors in docs example code

- Blocks should open with `do` and close with `end`.
- `...` is not valid Ruby syntax, so comment it out so that the user
  knows that it's a placeholder for "other things here".
- Reword the "header line details" in `Cask-Cookbook` otherwise RuboCop
  crashes even with an `end` because of the empty block. There was
  already an example of a valid header line in the first code block on
  the page, so it's not a big loss.
---
 docs/Cask-Cookbook.md    | 15 ++++++---------
 docs/Formula-Cookbook.md |  8 +++++---
 2 files changed, 11 insertions(+), 12 deletions(-)

diff --git a/docs/Cask-Cookbook.md b/docs/Cask-Cookbook.md
index 6b9d230528..48660d7bbd 100644
--- a/docs/Cask-Cookbook.md
+++ b/docs/Cask-Cookbook.md
@@ -29,13 +29,7 @@ Exception: `do` blocks such as `postflight` may enclose a block of pure Ruby cod
 
 ## Header line details
 
-The first non-comment line in a cask follows the form:
-
-```ruby
-cask "<cask-token>" do
-```
-
-[`<cask-token>`](#token-reference) should match the cask filename, without the `.rb` extension, enclosed in double quotes.
+The Cask name ([`<cask-token>`](#token-reference)) on the header line `cask <cask-token> do` should match the cask filename, without the `.rb` extension, enclosed in double quotes.
 
 There are currently some arbitrary limitations on cask tokens which are in the process of being removed. GitHub Actions will catch any errors during the transition.
 
@@ -1197,6 +1191,7 @@ cask "libreoffice" do
 
   url "https://download.documentfoundation.org/libreoffice/stable/#{version}/mac/#{folder}/LibreOffice_#{version}_MacOS_#{arch}.dmg",
       verified: "download.documentfoundation.org/libreoffice/stable/"
+end
 ```
 
 If the version number is different for each architecture, locate the unique `version` and (if checked) `sha256` stanzas within `on_arm` and `on_intel` blocks. Example (from [inkscape.rb](https://github.com/Homebrew/homebrew-cask/blob/11f6966bf17628b98895d64a61a4fb0bc1bb31bf/Casks/i/inkscape.rb#L1-L13)):
@@ -1215,6 +1210,7 @@ cask "inkscape" do
   end
 
   url "https://inkscape.org/gallery/item/#{version.csv.second}/Inkscape-#{version.csv.first}_#{arch}.dmg"
+end
 ```
 
 To adjust the installed version depending on the current macOS release, use a series of `on_<system>` blocks that cover the range of supported releases. Each block can contain stanzas that set which version to download and customize installation/uninstallation and livecheck behaviour for one or more releases. Example (from [calibre.rb](https://github.com/Homebrew/homebrew-cask/blob/482c34e950da8d649705f4aaea7b760dcb4b5402/Casks/c/calibre.rb#L1-L34)):
@@ -1244,6 +1240,7 @@ cask "calibre" do
       strategy :github_latest
     end
   end
+end
 ```
 
 Such `on_<system>` blocks can be nested and contain other stanzas not listed here. Examples: [calhash.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/c/calhash.rb), [openzfs.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/o/openzfs.rb), [r.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/r/r.rb), [wireshark.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/w/wireshark.rb)
@@ -1260,7 +1257,7 @@ In the exceptional case that the cask DSL is insufficient, it is possible to def
 cask "myapp" do
   module Utils
     def self.arbitrary_method
-      ...
+      # ...
     end
   end
 
@@ -1270,7 +1267,7 @@ cask "myapp" do
 
   url "https://#{Utils.arbitrary_method}"
   homepage "https://www.example.com/"
-  ...
+  # ...
 end
 ```
 
diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index 1e33b009cb..90cdecdf3c 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -546,7 +546,7 @@ end
 
 ```ruby
 stable do
-  # some other things...
+  # ...
 
   patch do
     url "https://example.com/example_patch.diff"
@@ -700,6 +700,7 @@ class Nginx < Formula
   url "https://nginx.org/download/nginx-1.23.2.tar.gz", using: :homebrew_curl
   sha256 "a80cc272d3d72aaee70aa8b517b4862a635c0256790434dbfc4d618a999b0b46"
   head "https://hg.nginx.org/nginx/", using: :hg
+end
 ```
 
 Homebrew offers these anonymous download strategies.
@@ -890,13 +891,14 @@ If you want to add an [`option`](https://rubydoc.brew.sh/Formula#option-class_me
 
 ```ruby
 class Yourformula < Formula
-  ...
+  # ...
   option "with-ham", "Description of the option"
   option "without-spam", "Another description"
 
   depends_on "foo" => :optional  # automatically adds a with-foo option
   depends_on "bar" => :recommended  # automatically adds a without-bar option
-  ...
+  # ...
+end
 ```
 
 And then to define the effects the [`option`](https://rubydoc.brew.sh/Formula#option-class_method)s have:

From 1fe968e937588e857ce30a2bd331f4b2098abdd5 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Sun, 21 Jan 2024 23:21:44 +0000
Subject: [PATCH 05/16] Run `brew style` for docs as part of the docs CI job

- Let's see how this goes.
---
 .github/workflows/docs.yml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 54b7f74f34..81004f9add 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -40,6 +40,10 @@ jobs:
         working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs
         run: bundle exec rake lint
 
+      - name: Check code blocks conform to our Ruby style guide
+        working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs
+        run: brew style -- *.md
+
       - name: Build the site and check for broken links
         working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs
         run: |

From 6485324b189b0114a59d9297fb75155529ad4c1b Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Tue, 23 Jan 2024 21:26:14 +0000
Subject: [PATCH 06/16] Fix `Sorbet/` group offenses in docs example code

- T::Sig hasn't been needed in every file for a long time.
---
 docs/Typechecking.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/Typechecking.md b/docs/Typechecking.md
index d77689d615..0b4b4b1118 100644
--- a/docs/Typechecking.md
+++ b/docs/Typechecking.md
@@ -12,8 +12,6 @@ The `sig` method is used to annotate method signatures. Here's a simple example:
 
 ```ruby
 class MyClass
-  extend T::Sig
-
   sig { params(name: String).returns(String) }
   def my_method(name)
     "Hello, #{name}!"

From af90f0858a03c4078bdc9eb7641d3398d87ebb89 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Sun, 21 Jan 2024 22:25:33 +0000
Subject: [PATCH 07/16] Fix RuboCop `Layout/` group offenses in docs example
 code

---
 docs/Adding-Software-to-Homebrew.md           |  2 +-
 docs/Cask-Cookbook.md                         | 12 ++--
 docs/Formula-Cookbook.md                      | 56 +++++++++----------
 ...Homebrew-homebrew-core-Maintainer-Guide.md |  4 +-
 docs/License-Guidelines.md                    |  4 +-
 5 files changed, 39 insertions(+), 39 deletions(-)

diff --git a/docs/Adding-Software-to-Homebrew.md b/docs/Adding-Software-to-Homebrew.md
index 342e900e0b..f084cbffea 100644
--- a/docs/Adding-Software-to-Homebrew.md
+++ b/docs/Adding-Software-to-Homebrew.md
@@ -242,7 +242,7 @@ Example:
 1. So, the `app` stanza should include the subfolder as a relative path:
 
    ```ruby
-   app "Simple Floating Clock/SimpleFloatingClock.app"
+app "Simple Floating Clock/SimpleFloatingClock.app"
    ```
 
 ### Testing and auditing the cask
diff --git a/docs/Cask-Cookbook.md b/docs/Cask-Cookbook.md
index 48660d7bbd..0febfdd21e 100644
--- a/docs/Cask-Cookbook.md
+++ b/docs/Cask-Cookbook.md
@@ -846,12 +846,12 @@ An example, with commonly used signals in ascending order of severity:
 
 ```ruby
 uninstall signal: [
-            ["TERM", "fr.madrau.switchresx.daemon"],
-            ["QUIT", "fr.madrau.switchresx.daemon"],
-            ["INT",  "fr.madrau.switchresx.daemon"],
-            ["HUP",  "fr.madrau.switchresx.daemon"],
-            ["KILL", "fr.madrau.switchresx.daemon"],
-          ]
+  ["TERM", "fr.madrau.switchresx.daemon"],
+  ["QUIT", "fr.madrau.switchresx.daemon"],
+  ["INT",  "fr.madrau.switchresx.daemon"],
+  ["HUP",  "fr.madrau.switchresx.daemon"],
+  ["KILL", "fr.madrau.switchresx.daemon"],
+]
 ```
 
 Note that when multiple running processes match the given bundle ID, all matching processes will be signaled.
diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index 90cdecdf3c..03c05d3091 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -168,8 +168,8 @@ A `Hash` (e.g. `=>`) adds information to a dependency. Given a string or symbol,
 * `:recommended` (not allowed in `Homebrew/homebrew-core`) generates an implicit `without-foo` option, meaning that the dependency is enabled by default and the user must pass `--without-foo` to disable this dependency. The default description can be overridden using the [`option`](https://rubydoc.brew.sh/Formula#option-class_method) syntax (in this case, the [`option` declaration](#adding-optional-steps) must precede the dependency):
 
   ```ruby
-  option "with-foo", "Compile with foo bindings" # This overrides the generated description if you want to
-  depends_on "foo" => :optional # Generated description would otherwise be "Build with foo support"
+option "with-foo", "Compile with foo bindings" # This overrides the generated description if you want to
+depends_on "foo" => :optional # Generated description would otherwise be "Build with foo support"
   ```
 
 * `"<option-name>"` (not allowed in `Homebrew/homebrew-core`) requires a dependency to have been built with the specified option.
@@ -856,25 +856,25 @@ Several other utilities for Ruby's [`Pathname`](https://rubydoc.brew.sh/Pathname
 * To perform several operations within a directory, enclose them within a  [`cd <path> do`](https://rubydoc.brew.sh/Pathname#cd-instance_method) block:
 
   ```ruby
-  cd "src" do
-    system "./configure",  "--disable-debug", "--prefix=#{prefix}"
-    system "make", "install"
-  end
+cd "src" do
+  system "./configure", "--disable-debug", "--prefix=#{prefix}"
+  system "make", "install"
+end
   ```
 
 * To surface one or more binaries buried in `libexec` or a macOS `.app` package, use [`write_exec_script`](https://rubydoc.brew.sh/Pathname#write_exec_script-instance_method) or [`write_jar_script`](https://rubydoc.brew.sh/Pathname#write_jar_script-instance_method):
 
   ```ruby
-  bin.write_exec_script (libexec/"bin").children
-  bin.write_exec_script prefix/"Package.app/Contents/MacOS/package"
-  bin.write_jar_script libexec/jar_file, "jarfile", java_version: "11"
+bin.write_exec_script (libexec/"bin").children
+bin.write_exec_script prefix/"Package.app/Contents/MacOS/package"
+bin.write_jar_script libexec/jar_file, "jarfile", java_version: "11"
   ```
 
 * For binaries that require setting one or more environment variables to function properly, use [`write_env_script`](https://rubydoc.brew.sh/Pathname#write_env_script-instance_method) or [`env_script_all_files`](https://rubydoc.brew.sh/Pathname#env_script_all_files-instance_method):
 
   ```ruby
-  (bin/"package").write_env_script libexec/"package", PACKAGE_ROOT: libexec
-  bin.env_script_all_files(libexec/"bin", PERL5LIB: ENV["PERL5LIB"])
+(bin/"package").write_env_script libexec/"package", PACKAGE_ROOT: libexec
+bin.env_script_all_files(libexec/"bin", PERL5LIB: ENV["PERL5LIB"])
   ```
 
 ### Rewriting a script shebang
@@ -895,8 +895,8 @@ class Yourformula < Formula
   option "with-ham", "Description of the option"
   option "without-spam", "Another description"
 
-  depends_on "foo" => :optional  # automatically adds a with-foo option
-  depends_on "bar" => :recommended  # automatically adds a without-bar option
+  depends_on "foo" => :optional # automatically adds a with-foo option
+  depends_on "bar" => :recommended # automatically adds a without-bar option
   # ...
 end
 ```
@@ -943,10 +943,10 @@ There are two ways to add `launchd` plists and `systemd` services to a formula,
 1. If the package already provides a service file the formula can reference it by name:
 
    ```ruby
-   service do
-     name macos: "custom.launchd.name",
-          linux: "custom.systemd.name"
-   end
+service do
+  name macos: "custom.launchd.name",
+       linux: "custom.systemd.name"
+end
    ```
 
    To find the file we append `.plist` to the `launchd` service name and `.service` to the `systemd` service name internally.
@@ -955,20 +955,20 @@ There are two ways to add `launchd` plists and `systemd` services to a formula,
 
    ```ruby
    # 1. An individual command
-   service do
-     run opt_bin/"script"
-   end
+service do
+  run opt_bin/"script"
+end
 
    # 2. A command with arguments
-   service do
-     run [opt_bin/"script", "--config", etc/"dir/config.yml"]
-   end
+service do
+  run [opt_bin/"script", "--config", etc/"dir/config.yml"]
+end
 
    # 3. OS specific commands (If you omit one, the service file won't get generated for that OS.)
-   service do
-     run macos: [opt_bin/"macos_script", "standalone"],
-         linux: var/"special_linux_script"
-   end
+service do
+  run macos: [opt_bin/"macos_script", "standalone"],
+      linux: var/"special_linux_script"
+end
    ```
 
 #### Service block methods
@@ -1159,7 +1159,7 @@ If a project's makefile will not run in parallel, try to deparallelize by adding
 
 ```ruby
 ENV.deparallelize
-system "make"  # separate compilation and installation steps
+system "make" # separate compilation and installation steps
 system "make", "install"
 ```
 
diff --git a/docs/Homebrew-homebrew-core-Maintainer-Guide.md b/docs/Homebrew-homebrew-core-Maintainer-Guide.md
index 1989e8cd1c..074cc2388c 100644
--- a/docs/Homebrew-homebrew-core-Maintainer-Guide.md
+++ b/docs/Homebrew-homebrew-core-Maintainer-Guide.md
@@ -158,9 +158,9 @@ Solution:
 
 ```ruby
 if OS.mac?
-    system ENV.cc, "-I#{include}", "-L#{lib}", "-lmagic", "test.c", "-o", "test"
+  system ENV.cc, "-I#{include}", "-L#{lib}", "-lmagic", "test.c", "-o", "test"
 else
-    system ENV.cc, "test.c", "-I#{include}", "-L#{lib}", "-lmagic", "-o", "test"
+  system ENV.cc, "test.c", "-I#{include}", "-L#{lib}", "-lmagic", "-o", "test"
 end
 ```
 
diff --git a/docs/License-Guidelines.md b/docs/License-Guidelines.md
index dade76c70d..8811a14da0 100644
--- a/docs/License-Guidelines.md
+++ b/docs/License-Guidelines.md
@@ -68,8 +68,8 @@ These expressions can be nested as needed:
 license any_of: [
   "MIT",
   :public_domain,
-  all_of: ["0BSD", "Zlib", "Artistic-1.0+"],
-  "Apache-2.0" => { with: "LLVM-exception" },
+  { all_of: ["0BSD", "Zlib", "Artistic-1.0+"],
+  "Apache-2.0" => { with: "LLVM-exception" } },
 ]
 ```
 

From 9b6903f50b07d85443d2e4717434b1f24a395ea7 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Tue, 23 Jan 2024 21:49:08 +0000
Subject: [PATCH 08/16] Fix RuboCop `Style/` group offenses in docs example
 code

---
 docs/Cask-Cookbook.md    | 4 ++--
 docs/Formula-Cookbook.md | 6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/Cask-Cookbook.md b/docs/Cask-Cookbook.md
index 0febfdd21e..694abf8c7f 100644
--- a/docs/Cask-Cookbook.md
+++ b/docs/Cask-Cookbook.md
@@ -1076,7 +1076,7 @@ we can use:
 
 ```ruby
 version "1.2.3"
-url "https://example.com/file-version-#{version.delete('.')}.dmg"
+url "https://example.com/file-version-#{version.delete(".")}.dmg"
 ```
 
 We can also leverage the power of regular expressions. So instead of:
@@ -1090,7 +1090,7 @@ we can use:
 
 ```ruby
 version "1.2.3build4"
-url "https://example.com/#{version.sub(%r{build\d+}, '')}/file-version-#{version}.dmg"
+url "https://example.com/#{version.sub(/build\d+/, "")}/file-version-#{version}.dmg"
 ```
 
 #### `version` methods
diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index 03c05d3091..ecbe007392 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -271,7 +271,7 @@ And install any bins, and munge their shebang lines, with:
 
 ```ruby
 bin.install libexec/"bin/<bin>"
-bin.env_script_all_files(libexec/"bin", GEM_HOME: ENV["GEM_HOME"])
+bin.env_script_all_files(libexec/"bin", GEM_HOME: ENV.fetch("GEM_HOME", nil))
 ```
 
 ### Python dependencies
@@ -730,7 +730,7 @@ class MyDownloadStrategy < SomeHomebrewDownloadStrategy
 end
 
 class Foo < Formula
-  url "something", :using => MyDownloadStrategy
+  url "something", using: MyDownloadStrategy
 end
 ```
 
@@ -874,7 +874,7 @@ bin.write_jar_script libexec/jar_file, "jarfile", java_version: "11"
 
   ```ruby
 (bin/"package").write_env_script libexec/"package", PACKAGE_ROOT: libexec
-bin.env_script_all_files(libexec/"bin", PERL5LIB: ENV["PERL5LIB"])
+bin.env_script_all_files(libexec/"bin", PERL5LIB: ENV.fetch("PERL5LIB", nil))
   ```
 
 ### Rewriting a script shebang

From e5ae67f90627a0769c33ab81f2ad4f557c3aa9b3 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Tue, 23 Jan 2024 23:04:30 +0000
Subject: [PATCH 09/16] Fix RuboCop `FormulaAudit/` group offenses for docs
 code examples

---
 docs/Cask-Cookbook.md              |  2 +-
 docs/Formula-Cookbook.md           | 21 +++++-----
 docs/Manpage.md                    |  2 +-
 docs/Node-for-Formula-Authors.md   |  4 +-
 docs/Python-for-Formula-Authors.md | 64 +++++++++++++++++++++---------
 5 files changed, 61 insertions(+), 32 deletions(-)

diff --git a/docs/Cask-Cookbook.md b/docs/Cask-Cookbook.md
index 694abf8c7f..d82d4bb4a2 100644
--- a/docs/Cask-Cookbook.md
+++ b/docs/Cask-Cookbook.md
@@ -1261,11 +1261,11 @@ cask "myapp" do
     end
   end
 
-  name "MyApp"
   version "1.0"
   sha256 "a32565cdb1673f4071593d4cc9e1c26bc884218b62fef8abc450daa47ba8fa92"
 
   url "https://#{Utils.arbitrary_method}"
+  name "MyApp"
   homepage "https://www.example.com/"
   # ...
 end
diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index ecbe007392..a37defc1bc 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -145,14 +145,14 @@ Special exceptions are OpenSSL and LibreSSL. Things that use either *should* be
 
 ```ruby
 class Foo < Formula
-  depends_on "pkg-config"
-  depends_on "jpeg"
-  depends_on "gtk+" => :optional
-  depends_on "readline" => :recommended
   depends_on "httpd" => [:build, :test]
-  depends_on arch: :x86_64
-  depends_on macos: :high_sierra
   depends_on xcode: ["9.3", :build]
+  depends_on arch: :x86_64
+  depends_on "jpeg"
+  depends_on macos: :high_sierra
+  depends_on "pkg-config"
+  depends_on "readline" => :recommended
+  depends_on "gtk+" => :optional
 end
 ```
 
@@ -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
 ```
@@ -686,6 +686,7 @@ When parsing a download URL, Homebrew auto-detects the resource type it points t
 ```ruby
 class Foo < Formula
   homepage "https://github.com/some/package"
+  description "Some package"
   url "https://github.com/some/package.git",
       tag:      "v1.6.2",
       revision: "344cd2ee3463abab4c16ac0f9529a846314932a2"
@@ -697,6 +698,7 @@ If not inferable, specify which of Homebrew’s built-in download strategies to
 ```ruby
 class Nginx < Formula
   homepage "https://nginx.org/"
+  description "Some package"
   url "https://nginx.org/download/nginx-1.23.2.tar.gz", using: :homebrew_curl
   sha256 "a80cc272d3d72aaee70aa8b517b4862a635c0256790434dbfc4d618a999b0b46"
   head "https://hg.nginx.org/nginx/", using: :hg
@@ -731,6 +733,7 @@ end
 
 class Foo < Formula
   url "something", using: MyDownloadStrategy
+  description "Some package"
 end
 ```
 
@@ -895,8 +898,8 @@ class Yourformula < Formula
   option "with-ham", "Description of the option"
   option "without-spam", "Another description"
 
-  depends_on "foo" => :optional # automatically adds a with-foo option
-  depends_on "bar" => :recommended # automatically adds a without-bar option
+  depends_on "bar" => :recommended
+  depends_on "foo" => :optional # automatically adds a with-foo option # automatically adds a without-bar option
   # ...
 end
 ```
diff --git a/docs/Manpage.md b/docs/Manpage.md
index d4c040ca9a..371787b6e7 100644
--- a/docs/Manpage.md
+++ b/docs/Manpage.md
@@ -1179,7 +1179,7 @@ Display the path to the file being used when invoking `brew` *`cmd`*.
 Summarise contributions to Homebrew repositories.
 
 * `--repositories`:
-  Specify a comma-separated list of repositories to search. Supported repositories: `brew`, `core`, `cask`, `aliases`, `autoupdate`, `bundle`, `command-not-found`, `test-bot`, `services`, `cask-fonts` and `cask-versions`. Omitting this flag, or specifying `--repositories=primary`, searches only the main repositories: brew,core,cask. Specifying `--repositories=all`, searches all repositories. 
+  Specify a comma-separated list of repositories to search. Supported repositories: `brew`, `core`, `cask`, `aliases`, `autoupdate`, `bundle`, `command-not-found`, `test-bot`, `services`, `cask-fonts` and `cask-versions`. Omitting this flag, or specifying `--repositories=primary`, searches only the main repositories: brew,core,cask. Specifying `--repositories=all`, searches all repositories.
 * `--from`:
   Date (ISO-8601 format) to start searching contributions. Omitting this flag searches the last year.
 * `--to`:
diff --git a/docs/Node-for-Formula-Authors.md b/docs/Node-for-Formula-Authors.md
index 65e9584e22..7f1c4cd9ee 100644
--- a/docs/Node-for-Formula-Authors.md
+++ b/docs/Node-for-Formula-Authors.md
@@ -91,10 +91,10 @@ Installing a standard Node module based formula would look like this:
 require "language/node"
 
 class Foo < Formula
-  desc "..."
+  desc "Description"
   homepage "..."
   url "https://registry.npmjs.org/foo/-/foo-1.4.2.tgz"
-  sha256 "..."
+  sha256 "abc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"
 
   depends_on "node"
   # uncomment if there is a native addon inside the dependency tree
diff --git a/docs/Python-for-Formula-Authors.md b/docs/Python-for-Formula-Authors.md
index d74b5b4502..213cbf0170 100644
--- a/docs/Python-for-Formula-Authors.md
+++ b/docs/Python-for-Formula-Authors.md
@@ -50,26 +50,46 @@ Homebrew provides helper methods for instantiating and populating virtualenvs. Y
 For most applications, all you will need to write is:
 
 ```ruby
-def install
-  virtualenv_install_with_resources
+class Foo < Formula
+  include Language::Python::Virtualenv
+
+  name "foo"
+  desc "Bar"
+  homepage "https://example.com"
+  url "..."
+  sha256 "abc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"
+
+  def install
+    virtualenv_install_with_resources
+  end
 end
 ```
 
 This is exactly the same as writing:
 
 ```ruby
-def install
-  # Create a virtualenv in `libexec`. If your app needs Python 3, make sure that
-  # `depends_on "python"` is declared, and use `virtualenv_create(libexec, "python3")`.
-  venv = virtualenv_create(libexec)
-  # Install all of the resources declared on the formula into the virtualenv.
-  venv.pip_install resources
-  # `pip_install_and_link` takes a look at the virtualenv's bin directory
-  # before and after installing its argument. New scripts will be symlinked
-  # into `bin`. `pip_install_and_link buildpath` will install the package
-  # that the formula points to, because buildpath is the location where the
-  # formula's tarball was unpacked.
-  venv.pip_install_and_link buildpath
+class Foo < Formula
+  include Language::Python::Virtualenv
+
+  name "foo"
+  desc "Bar"
+  homepage "https://example.com"
+  url "..."
+  sha256 "abc123"
+
+  def install
+    # Create a virtualenv in `libexec`. If your app needs Python 3, make sure that
+    # `depends_on "python"` is declared, and use `virtualenv_create(libexec, "python3")`.
+    venv = virtualenv_create(libexec)
+    # Install all of the resources declared on the formula into the virtualenv.
+    venv.pip_install resources
+    # `pip_install_and_link` takes a look at the virtualenv's bin directory
+    # before and after installing its argument. New scripts will be symlinked
+    # into `bin`. `pip_install_and_link buildpath` will install the package
+    # that the formula points to, because buildpath is the location where the
+    # formula's tarball was unpacked.
+    venv.pip_install_and_link buildpath
+  end
 end
 ```
 
@@ -102,12 +122,18 @@ end
 You can also use the more verbose form and request that specific resources be installed:
 
 ```ruby
-def install
-  venv = virtualenv_create(libexec)
-  %w[six parsedatetime].each do |r|
-    venv.pip_install resource(r)
+class Foo < Formula
+  include Language::Python::Virtualenv
+
+  url "..."
+
+  def install
+    venv = virtualenv_create(libexec)
+    %w[six parsedatetime].each do |r|
+      venv.pip_install resource(r)
+    end
+    venv.pip_install_and_link buildpath
   end
-  venv.pip_install_and_link buildpath
 end
 ```
 

From 00b47d1fec0e5c8a40761e9358b4ffba73d3422a Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Tue, 23 Jan 2024 23:06:04 +0000
Subject: [PATCH 10/16] 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 |  2 +-
 Library/Homebrew/style.rb  |  2 ++
 docs/.rubocop.yml          | 25 +++++++++++++++++++++++++
 docs/Formula-Cookbook.md   |  2 +-
 4 files changed, 29 insertions(+), 2 deletions(-)
 create mode 100644 docs/.rubocop.yml

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 81004f9add..8e9e40014a 100644
--- a/.github/workflows/docs.yml
+++ b/.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
diff --git a/Library/Homebrew/style.rb b/Library/Homebrew/style.rb
index 6c8240c0f5..6d803d19a8 100644
--- a/Library/Homebrew/style.rb
+++ b/Library/Homebrew/style.rb
@@ -126,6 +126,8 @@ module Homebrew
       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
diff --git a/docs/.rubocop.yml b/docs/.rubocop.yml
new file mode 100644
index 0000000000..ff24053d66
--- /dev/null
+++ b/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
diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index a37defc1bc..3e2883eea2 100644
--- a/docs/Formula-Cookbook.md
+++ b/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
 ```

From aaddc66548a2c0617fe335e8afb057f39422c9dc Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Sat, 27 Jan 2024 12:30:00 +0000
Subject: [PATCH 11/16] Fix remaining RuboCop `FormulaAudit` offenses in
 example code

---
 docs/Adding-Software-to-Homebrew.md | 10 +++----
 docs/Formula-Cookbook.md            | 45 +++++++++++++++++++++++------
 docs/Node-for-Formula-Authors.md    |  5 ++--
 docs/Python-for-Formula-Authors.md  |  8 +++--
 4 files changed, 50 insertions(+), 18 deletions(-)

diff --git a/docs/Adding-Software-to-Homebrew.md b/docs/Adding-Software-to-Homebrew.md
index f084cbffea..0bedc6eae3 100644
--- a/docs/Adding-Software-to-Homebrew.md
+++ b/docs/Adding-Software-to-Homebrew.md
@@ -175,13 +175,13 @@ This will open `EDITOR` with a template for your new cask, to be stored in the f
 
 ```ruby
 cask "my-new-cask" do
-  version ""
-  sha256 ""
+  version "fill in the version here"
+  sha256 "fill in the sha256 here"
 
   url "download-url"
-  name ""
-  desc ""
-  homepage ""
+  name "fill in the name"
+  desc "Fill in the description here"
+  homepage "fill in the homepage here"
 
   livecheck do
     url ""
diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index 3e2883eea2..db5aa895a2 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -66,11 +66,11 @@ This creates `$(brew --repository)/Library/Taps/homebrew/homebrew-core/Formula/f
 
 ```ruby
 class Foo < Formula
-  desc ""
-  homepage ""
+  desc "Fill in a one-line description of your formula"
+  homepage "https://your.homepage/"
   url "https://example.com/foo-0.1.tar.gz"
   sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7"
-  license ""
+  license "Fill in a license identifier"
 
   # depends_on "cmake" => :build
 
@@ -145,6 +145,9 @@ Special exceptions are OpenSSL and LibreSSL. Things that use either *should* be
 
 ```ruby
 class Foo < Formula
+  desc "Example formula"
+  homepage "https://example.com"
+
   depends_on "httpd" => [:build, :test]
   depends_on xcode: ["9.3", :build]
   depends_on arch: :x86_64
@@ -153,6 +156,8 @@ class Foo < Formula
   depends_on "pkg-config"
   depends_on "readline" => :recommended
   depends_on "gtk+" => :optional
+
+  # ...
 end
 ```
 
@@ -284,6 +289,10 @@ If all else fails, you'll want to use [`resource`](https://rubydoc.brew.sh/Formu
 
 ```ruby
 class Foo < Formula
+  desc "Example formula"
+  homepage "https://example.com"
+  url "https://example.com/foo-1.0.tar.gz"
+
   resource "pycrypto" do
     url "https://files.pythonhosted.org/packages/60/db/645aa9af249f059cc3a368b118de33889219e0362141e75d4eaf6f80f163/pycrypto-2.6.1.tar.gz"
     sha256 "f2ce1e989b272cfcb677616763e0a2e7ec659effa67a88aa92b3a65528f60a3c"
@@ -662,6 +671,9 @@ Formulae can specify an alternate download for the upstream project’s developm
 
 ```ruby
 class Foo < Formula
+  desc "Description"
+  homepage "https://example.com"
+
   head "https://github.com/some/package.git", branch: "main" # the default is "master"
 end
 ```
@@ -670,6 +682,9 @@ You can also bundle the URL and any `head`-specific dependencies and resources i
 
 ```ruby
 class Foo < Formula
+  desc "Description"
+  homepage "https://example.com"
+
   head do
     url "https://svn.code.sf.net/p/project/code/trunk"
     depends_on "pkg-config" => :build
@@ -685,8 +700,8 @@ When parsing a download URL, Homebrew auto-detects the resource type it points t
 
 ```ruby
 class Foo < Formula
+  desc "Some package"
   homepage "https://github.com/some/package"
-  description "Some package"
   url "https://github.com/some/package.git",
       tag:      "v1.6.2",
       revision: "344cd2ee3463abab4c16ac0f9529a846314932a2"
@@ -697,8 +712,8 @@ If not inferable, specify which of Homebrew’s built-in download strategies to
 
 ```ruby
 class Nginx < Formula
+  desc "Some package"
   homepage "https://nginx.org/"
-  description "Some package"
   url "https://nginx.org/download/nginx-1.23.2.tar.gz", using: :homebrew_curl
   sha256 "a80cc272d3d72aaee70aa8b517b4862a635c0256790434dbfc4d618a999b0b46"
   head "https://hg.nginx.org/nginx/", using: :hg
@@ -732,8 +747,9 @@ class MyDownloadStrategy < SomeHomebrewDownloadStrategy
 end
 
 class Foo < Formula
+  desc "Some package"
+  homepage "https://example.com"
   url "something", using: MyDownloadStrategy
-  description "Some package"
 end
 ```
 
@@ -894,6 +910,10 @@ If you want to add an [`option`](https://rubydoc.brew.sh/Formula#option-class_me
 
 ```ruby
 class Yourformula < Formula
+  desc "Description"
+  homepage "https://example.com"
+  url "https://example.com/yourformula-1.0.tar.gz"
+  sha256 "abc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"
   # ...
   option "with-ham", "Description of the option"
   option "without-spam", "Another description"
@@ -925,9 +945,16 @@ end
 Any initialization steps that aren't necessarily part of the install process can be located in a `post_install` block, such as setup commands or data directory creation. This block can be re-run separately with `brew postinstall <formula>`.
 
 ```ruby
-def post_install
-  rm_f pkgetc/"cert.pem"
-  pkgetc.install_symlink Formula["ca-certificates"].pkgetc/"cert.pem"
+class Foo < Formula
+  desc "Description"
+  homepage "https://example.com"
+  url "https://example.com/foo-1.0.tar.gz"
+
+  def post_install
+    rm_f pkgetc/"cert.pem"
+    pkgetc.install_symlink Formula["ca-certificates"].pkgetc/"cert.pem"
+  end
+  # ...
 end
 ```
 
diff --git a/docs/Node-for-Formula-Authors.md b/docs/Node-for-Formula-Authors.md
index 7f1c4cd9ee..c44cd667ed 100644
--- a/docs/Node-for-Formula-Authors.md
+++ b/docs/Node-for-Formula-Authors.md
@@ -92,7 +92,7 @@ require "language/node"
 
 class Foo < Formula
   desc "Description"
-  homepage "..."
+  homepage "https://example.com"
   url "https://registry.npmjs.org/foo/-/foo-1.4.2.tgz"
   sha256 "abc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"
 
@@ -106,7 +106,8 @@ class Foo < Formula
   end
 
   test do
-    # add a meaningful test here
+    # add a meaningful test here, version isn't usually meaningful
+    assert_match version.to_s, shell_output("#{bin}/foo --version")
   end
 end
 ```
diff --git a/docs/Python-for-Formula-Authors.md b/docs/Python-for-Formula-Authors.md
index 213cbf0170..5aff5f096c 100644
--- a/docs/Python-for-Formula-Authors.md
+++ b/docs/Python-for-Formula-Authors.md
@@ -74,8 +74,8 @@ class Foo < Formula
   name "foo"
   desc "Bar"
   homepage "https://example.com"
-  url "..."
-  sha256 "abc123"
+  url "https://example.com/foo-1.0.tar.gz"
+  sha256 "abc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"
 
   def install
     # Create a virtualenv in `libexec`. If your app needs Python 3, make sure that
@@ -101,6 +101,8 @@ Installing a formula with dependencies will look like this:
 class Foo < Formula
   include Language::Python::Virtualenv
 
+  desc "Description"
+  homepage "https://example.com"
   url "..."
 
   resource "six" do
@@ -125,6 +127,8 @@ You can also use the more verbose form and request that specific resources be in
 class Foo < Formula
   include Language::Python::Virtualenv
 
+  desc "Description"
+  homepage "https://example.com"
   url "..."
 
   def install

From 3f5ae06ab1c49aee37758b2869bd63aa9870a7d2 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Sat, 27 Jan 2024 12:32:46 +0000
Subject: [PATCH 12/16] Allow a longer `Layout/LineLength` for just the bottle
 blocks

---
 docs/.rubocop.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/.rubocop.yml b/docs/.rubocop.yml
index ff24053d66..2e17bcfefa 100644
--- a/docs/.rubocop.yml
+++ b/docs/.rubocop.yml
@@ -12,9 +12,9 @@ AllCops:
 FormulaAudit/Comments:
   Enabled: false
 
-# The bottle block line length is long in its full form.
 Layout/LineLength:
-  Max: 123
+  Exclude:
+  - Bottles.md # The bottle block line length is long in its full form.
 
 # Apparently Casks are allowed to have constant definitions in blocks and we document this.
 Lint/ConstantDefinitionInBlock:

From 3955a70a265a7c68b809b84df841ffdd0bb72455 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Mon, 29 Jan 2024 22:39:05 +0000
Subject: [PATCH 13/16] Delete easily outdated template docs for `brew create`

---
 docs/Adding-Software-to-Homebrew.md | 27 ++-------------------------
 docs/Formula-Cookbook.md            | 27 ++-------------------------
 2 files changed, 4 insertions(+), 50 deletions(-)

diff --git a/docs/Adding-Software-to-Homebrew.md b/docs/Adding-Software-to-Homebrew.md
index 0bedc6eae3..d06e4dc090 100644
--- a/docs/Adding-Software-to-Homebrew.md
+++ b/docs/Adding-Software-to-Homebrew.md
@@ -165,36 +165,13 @@ If the `generate_cask_token` script does not work for you, see [Cask Token Detai
 
 #### Creating the cask file
 
-Once you know the token, create your cask with the handy-dandy `brew create --cask` command:
+Once you know the token, create your cask with the `brew create --cask` command:
 
 ```bash
 brew create --cask download-url --set-name my-new-cask
 ```
 
-This will open `EDITOR` with a template for your new cask, to be stored in the file `my-new-cask.rb`. Running the `create` command above will get you a template that looks like this:
-
-```ruby
-cask "my-new-cask" do
-  version "fill in the version here"
-  sha256 "fill in the sha256 here"
-
-  url "download-url"
-  name "fill in the name"
-  desc "Fill in the description here"
-  homepage "fill in the homepage here"
-
-  livecheck do
-    url ""
-    strategy ""
-  end
-
-  depends_on macos: ""
-
-  app ""
-
-  zap trash: ""
-end
-```
+This will open `EDITOR` with a template for your new cask, to be stored in the file `my-new-cask.rb`.
 
 #### Cask stanzas
 
diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index db5aa895a2..17986b770b 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -60,33 +60,10 @@ Run `brew create` with a URL to the source tarball:
 brew create https://example.com/foo-0.1.tar.gz
 ```
 
+This creates `$(brew --repository)/Library/Taps/homebrew/homebrew-core/Formula/f/foo.rb` and opens it in your `EDITOR`.
+
 Passing in `--ruby` or `--python` will populate various defaults commonly useful for projects written in those languages.
 
-This creates `$(brew --repository)/Library/Taps/homebrew/homebrew-core/Formula/f/foo.rb` and opens it in your `EDITOR`. If run without any options to customize the output for specific build systems (check `brew create --help` to see which are available) it'll look something like:
-
-```ruby
-class Foo < Formula
-  desc "Fill in a one-line description of your formula"
-  homepage "https://your.homepage/"
-  url "https://example.com/foo-0.1.tar.gz"
-  sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7"
-  license "Fill in a license identifier"
-
-  # depends_on "cmake" => :build
-
-  def install
-    # ENV.deparallelize
-    system "./configure", *std_configure_args, "--disable-silent-rules"
-    # system "cmake", "-S", ".", "-B", "build", *std_cmake_args
-    system "make", "install"
-  end
-
-  test do
-    system "false"
-  end
-end
-```
-
 If `brew` said `Warning: Version cannot be determined from URL` when doing the `create` step, you’ll need to explicitly add the correct [`version`](https://rubydoc.brew.sh/Formula#version-class_method) to the formula and then save the formula.
 
 Homebrew will try to guess the formula’s name from its URL. If it fails to do so you can override this with `brew create <URL> --set-name <name>`.

From 3ee62bb244704ac0119f371cdea6a7cebe9f41d1 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Mon, 29 Jan 2024 22:43:36 +0000
Subject: [PATCH 14/16] Update example formula descriptions

---
 docs/Formula-Cookbook.md         | 2 +-
 docs/Node-for-Formula-Authors.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index 17986b770b..1de3d75f6c 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -689,7 +689,7 @@ If not inferable, specify which of Homebrew’s built-in download strategies to
 
 ```ruby
 class Nginx < Formula
-  desc "Some package"
+  desc "HTTP(S) server and reverse proxy, and IMAP/POP3 proxy server"
   homepage "https://nginx.org/"
   url "https://nginx.org/download/nginx-1.23.2.tar.gz", using: :homebrew_curl
   sha256 "a80cc272d3d72aaee70aa8b517b4862a635c0256790434dbfc4d618a999b0b46"
diff --git a/docs/Node-for-Formula-Authors.md b/docs/Node-for-Formula-Authors.md
index c44cd667ed..9a709135d9 100644
--- a/docs/Node-for-Formula-Authors.md
+++ b/docs/Node-for-Formula-Authors.md
@@ -91,7 +91,7 @@ Installing a standard Node module based formula would look like this:
 require "language/node"
 
 class Foo < Formula
-  desc "Description"
+  desc "An example formula"
   homepage "https://example.com"
   url "https://registry.npmjs.org/foo/-/foo-1.4.2.tgz"
   sha256 "abc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"

From bcd3a78f6d3da01b8bdb3ed5bba4ef3fec0b5a96 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Fri, 2 Feb 2024 15:24:17 +0000
Subject: [PATCH 15/16] Ignore the generated manpage; reinstate its trailing
 whitespace

---
 docs/.rubocop.yml | 1 +
 docs/Manpage.md   | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/.rubocop.yml b/docs/.rubocop.yml
index 2e17bcfefa..8097f0cbcf 100644
--- a/docs/.rubocop.yml
+++ b/docs/.rubocop.yml
@@ -6,6 +6,7 @@ AllCops:
   - ".mdl*.rb"
   - Rakefile
   - "_site/**/*"
+  - Manpage.md
 
 # These are included in docs deliberately to show what
 # `brew create` does and what the user should replace.
diff --git a/docs/Manpage.md b/docs/Manpage.md
index 371787b6e7..d4c040ca9a 100644
--- a/docs/Manpage.md
+++ b/docs/Manpage.md
@@ -1179,7 +1179,7 @@ Display the path to the file being used when invoking `brew` *`cmd`*.
 Summarise contributions to Homebrew repositories.
 
 * `--repositories`:
-  Specify a comma-separated list of repositories to search. Supported repositories: `brew`, `core`, `cask`, `aliases`, `autoupdate`, `bundle`, `command-not-found`, `test-bot`, `services`, `cask-fonts` and `cask-versions`. Omitting this flag, or specifying `--repositories=primary`, searches only the main repositories: brew,core,cask. Specifying `--repositories=all`, searches all repositories.
+  Specify a comma-separated list of repositories to search. Supported repositories: `brew`, `core`, `cask`, `aliases`, `autoupdate`, `bundle`, `command-not-found`, `test-bot`, `services`, `cask-fonts` and `cask-versions`. Omitting this flag, or specifying `--repositories=primary`, searches only the main repositories: brew,core,cask. Specifying `--repositories=all`, searches all repositories. 
 * `--from`:
   Date (ISO-8601 format) to start searching contributions. Omitting this flag searches the last year.
 * `--to`:

From ca92fca7706bc9f19fa202c731e7db3a5d48f47a Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Fri, 2 Feb 2024 15:37:01 +0000
Subject: [PATCH 16/16] Turn off `FormulaAudit/{Desc,Homepage}` for docs

- We don't need this blanket enabled, we only have a few docs where it actually matters that there's a description, it's just cruft having to invent descriptions.
---
 docs/.rubocop.yml                  |  6 ++++++
 docs/Formula-Cookbook.md           | 24 +++++++-----------------
 docs/Python-for-Formula-Authors.md |  6 ++----
 3 files changed, 15 insertions(+), 21 deletions(-)

diff --git a/docs/.rubocop.yml b/docs/.rubocop.yml
index 8097f0cbcf..62beffad29 100644
--- a/docs/.rubocop.yml
+++ b/docs/.rubocop.yml
@@ -13,6 +13,12 @@ AllCops:
 FormulaAudit/Comments:
   Enabled: false
 
+# This forces us to use dummy descriptions/homepages in example formulae which we don't need to clutter the docs with.
+FormulaAudit/Desc:
+  Enabled: false
+FormulaAudit/Homepage:
+  Enabled: false
+
 Layout/LineLength:
   Exclude:
   - Bottles.md # The bottle block line length is long in its full form.
diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index 1de3d75f6c..859da2481d 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -122,8 +122,7 @@ Special exceptions are OpenSSL and LibreSSL. Things that use either *should* be
 
 ```ruby
 class Foo < Formula
-  desc "Example formula"
-  homepage "https://example.com"
+  # ...
 
   depends_on "httpd" => [:build, :test]
   depends_on xcode: ["9.3", :build]
@@ -266,8 +265,7 @@ If all else fails, you'll want to use [`resource`](https://rubydoc.brew.sh/Formu
 
 ```ruby
 class Foo < Formula
-  desc "Example formula"
-  homepage "https://example.com"
+  # ...
   url "https://example.com/foo-1.0.tar.gz"
 
   resource "pycrypto" do
@@ -648,9 +646,7 @@ Formulae can specify an alternate download for the upstream project’s developm
 
 ```ruby
 class Foo < Formula
-  desc "Description"
-  homepage "https://example.com"
-
+  # ...
   head "https://github.com/some/package.git", branch: "main" # the default is "master"
 end
 ```
@@ -659,8 +655,7 @@ You can also bundle the URL and any `head`-specific dependencies and resources i
 
 ```ruby
 class Foo < Formula
-  desc "Description"
-  homepage "https://example.com"
+  # ...
 
   head do
     url "https://svn.code.sf.net/p/project/code/trunk"
@@ -677,8 +672,7 @@ When parsing a download URL, Homebrew auto-detects the resource type it points t
 
 ```ruby
 class Foo < Formula
-  desc "Some package"
-  homepage "https://github.com/some/package"
+  # ...
   url "https://github.com/some/package.git",
       tag:      "v1.6.2",
       revision: "344cd2ee3463abab4c16ac0f9529a846314932a2"
@@ -724,8 +718,6 @@ class MyDownloadStrategy < SomeHomebrewDownloadStrategy
 end
 
 class Foo < Formula
-  desc "Some package"
-  homepage "https://example.com"
   url "something", using: MyDownloadStrategy
 end
 ```
@@ -887,8 +879,7 @@ If you want to add an [`option`](https://rubydoc.brew.sh/Formula#option-class_me
 
 ```ruby
 class Yourformula < Formula
-  desc "Description"
-  homepage "https://example.com"
+  # ...
   url "https://example.com/yourformula-1.0.tar.gz"
   sha256 "abc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"
   # ...
@@ -923,8 +914,7 @@ Any initialization steps that aren't necessarily part of the install process can
 
 ```ruby
 class Foo < Formula
-  desc "Description"
-  homepage "https://example.com"
+  # ...
   url "https://example.com/foo-1.0.tar.gz"
 
   def post_install
diff --git a/docs/Python-for-Formula-Authors.md b/docs/Python-for-Formula-Authors.md
index 5aff5f096c..8caa7e2bfc 100644
--- a/docs/Python-for-Formula-Authors.md
+++ b/docs/Python-for-Formula-Authors.md
@@ -54,8 +54,7 @@ class Foo < Formula
   include Language::Python::Virtualenv
 
   name "foo"
-  desc "Bar"
-  homepage "https://example.com"
+  # ...
   url "..."
   sha256 "abc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"
 
@@ -72,8 +71,7 @@ class Foo < Formula
   include Language::Python::Virtualenv
 
   name "foo"
-  desc "Bar"
-  homepage "https://example.com"
+  # ...
   url "https://example.com/foo-1.0.tar.gz"
   sha256 "abc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"