Merge pull request #15924 from issyl0/docs-ci-broken-links

workflows/docs: Check for broken links using the existing `rake test` task

.github/workflows/docs.yml

@@ -32,17 +32,18 @@ jobs:
       - name: Install Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "2.7"
+          ruby-version: "3.1"
           bundler-cache: true
           working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs
 
       - name: Check Markdown syntax
         working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs
         run: bundle exec rake lint
 
-      - name: Build docs site
+      - name: Build the site and check for broken links
         working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs
-        run: bundle exec rake build
+        run: |
+          bundle exec rake test
 
   rubydoc:
     if: github.repository == 'Homebrew/brew'

docs/Adding-Software-to-Homebrew.md

@@ -86,7 +86,7 @@ cask "noisy" do
 end
 ```
 
-Here is a last example for `airdisplay`, which uses a `pkg` installer to install the application instead of a stand-alone application bundle (`.app`). Note the [`uninstall pkgutil` stanza](Cask-Cookbook.md#uninstall-key-pkgutil), which is needed to uninstall all files that were installed using the installer.
+Here is a last example for `airdisplay`, which uses a `pkg` installer to install the application instead of a stand-alone application bundle (`.app`). Note the [`uninstall pkgutil` stanza](Cask-Cookbook.md#uninstall-pkgutil), which is needed to uninstall all files that were installed using the installer.
 
 You will also see how to adapt `version` to the download `url`. Use [our custom `version` methods](Cask-Cookbook.md#version-methods) to do so, resorting to the standard [Ruby String methods](https://ruby-doc.org/core/String.html) when they don’t suffice.
 

docs/Formula-Cookbook.md

@@ -793,7 +793,7 @@ Note that in the context of Homebrew, [`libexec`](https://rubydoc.brew.sh/Formul
 
 ### File-level operations
 
-You can use the file utilities provided by Ruby's [`FileUtils`](https://www.ruby-doc.org/stdlib/libdoc/fileutils/rdoc/index.html). These are included in the [`Formula`](https://rubydoc.brew.sh/Formula) class, so you do not need the `FileUtils.` prefix to use them.
+You can use the file utilities provided by Ruby's [`FileUtils`](https://ruby-doc.org/stdlib-2.7.0/libdoc/fileutils/rdoc/FileUtils.html). These are included in the [`Formula`](https://rubydoc.brew.sh/Formula) class, so you do not need the `FileUtils.` prefix to use them.
 
 When creating symlinks, take special care to ensure they are *relative* symlinks. This makes it easier to create a relocatable bottle. For example, to create a symlink in `bin` to an executable in `libexec`, use:
 

docs/How-To-Organize-AGM.md

@@ -144,7 +144,8 @@ source of funding before seeking Homebrew funding.
 
 PLC, TSC, PL and maintainers can expect to have all reasonable, in-policy expenses covered while members will be considered on a case-by-case basis.
 
-See also the [Reimbursement Policy](Expense-and-Reimbursement-Policy.md#travel) for process and details on what is covered.
+Read the Expense and Reimbursement policy document in `Homebrew/homebrew-governance-private`.
+It contains the process and details on what is covered.
 It is important that all attendees expecting reimbursement stay in-policy.
 
 ## Ideas for future AGMs

docs/Installation.md

@@ -86,10 +86,10 @@ Create a Homebrew installation wherever you extract the tarball. Whichever `brew
 
 Uninstallation is documented in the [FAQ](FAQ.md).
 
-<a name="1"><sup>1</sup></a> For 32-bit or PPC support see [Tigerbrew](https://github.com/mistydemeo/tigerbrew).
+<a data-proofer-ignore name="1"><sup>1</sup></a> For 32-bit or PPC support see [Tigerbrew](https://github.com/mistydemeo/tigerbrew).
 
-<a name="2"><sup>2</sup></a> macOS 11 (Big Sur) or higher is best and supported, 10.11 (El Capitan) – 10.15 (Catalina) are unsupported but may work and 10.10 (Yosemite) and older will not run Homebrew at all. For 10.4 (Tiger) – 10.6 (Snow Leopard) see [Tigerbrew](https://github.com/mistydemeo/tigerbrew).
+<a data-proofer-ignore name="2"><sup>2</sup></a> macOS 11 (Big Sur) or higher is best and supported, 10.11 (El Capitan) – 10.15 (Catalina) are unsupported but may work and 10.10 (Yosemite) and older will not run Homebrew at all. For 10.4 (Tiger) – 10.6 (Snow Leopard) see [Tigerbrew](https://github.com/mistydemeo/tigerbrew).
 
-<a name="3"><sup>3</sup></a> You may need to install Xcode, the CLT, or both depending on the formula, to install a bottle (binary package) which is the only supported configuration. Downloading Xcode may require an Apple Developer account on older versions of Mac OS X. Sign up for free at [Apple's website](https://developer.apple.com/account/).
+<a data-proofer-ignore name="3"><sup>3</sup></a> You may need to install Xcode, the CLT, or both depending on the formula, to install a bottle (binary package) which is the only supported configuration. Downloading Xcode may require an Apple Developer account on older versions of Mac OS X. Sign up for free at [Apple's website](https://developer.apple.com/account/).
 
-<a name="4"><sup>4</sup></a> The one-liner installation method found on [brew.sh](https://brew.sh) uses the Bourne-again shell at `/bin/bash`. Notably, `zsh`, `fish`, `tcsh` and `csh` will not work.
+<a data-proofer-ignore name="4"><sup>4</sup></a> The one-liner installation method found on [brew.sh](https://brew.sh) uses the Bourne-again shell at `/bin/bash`. Notably, `zsh`, `fish`, `tcsh` and `csh` will not work.

docs/Python-for-Formula-Authors.md

@@ -4,7 +4,7 @@ This document explains how to successfully use Python in a Homebrew formula.
 
 Homebrew draws a distinction between Python **applications** and Python **libraries**. The difference is that users generally do not care that applications are written in Python; it is unusual that a user would expect to be able to `import foo` after installing an application. Examples of applications are [`ansible`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/a/ansible.rb) and [`jrnl`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/j/jrnl.rb).
 
-Python libraries exist to be imported by other Python modules; they are often dependencies of Python applications. They are usually no more than incidentally useful in a terminal. Examples of libraries are [`py2cairo`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/p/py2cairo.rb) and the bindings that are installed by [`protobuf`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/p/protobuf.rb).
+Python libraries exist to be imported by other Python modules; they are often dependencies of Python applications. They are usually no more than incidentally useful in a terminal. An example of a library is the bindings that are installed by [`protobuf`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/p/protobuf.rb).
 
 Bindings are a special case of libraries that allow Python code to interact with a library or application implemented in another language.
 
@@ -189,7 +189,7 @@ where `prefix` is the destination prefix (usually `libexec` or `prefix`).
 
 ### What is `--single-version-externally-managed`?
 
-`--single-version-externally-managed` ("SVEM") is a Setuptools-only [argument to `setup.py install`](https://setuptools.readthedocs.io/en/latest/setuptools.html?#install-run-easy-install-or-old-style-installation). The primary effect of SVEM is using Distutils to perform the install instead of Setuptools' `easy_install`.
+`--single-version-externally-managed` ("SVEM") is a [Setuptools](https://setuptools.readthedocs.io/en/latest/setuptools.html)-only argument to `setup.py install`. The primary effect of SVEM is using Distutils to perform the install instead of Setuptools' `easy_install`.
 
 `easy_install` does a few things that we need to avoid:
 

docs/Rakefile

@@ -19,19 +19,23 @@ task test: :build do
     "./_site",
     parallel: { in_threads: 4 },
     favicon: true,
-    http_status_ignore: [0, 403],
-    assume_extension: true,
+    ignore_status_codes: [0, 403],
     check_favicon: true,
     check_opengraph: true,
     check_html: true,
     check_img_http: true,
     enforce_https: true,
-    file_ignore: [
+    ignore_files: [
       %r{Kickstarter-Supporters},
     ],
-    url_ignore: [
-      "http://formulae.brew.sh",
-      %r{https://github.com/Homebrew/brew/edit/gh-pages//},
-    ]
+    ignore_urls: [
+      %r{https://formulae.brew.sh"},
+      %r{https://github.com/}
+    ],
+    cache: {
+      timeframe: {
+        external: "1h"
+      }
+    }
   ).run
 end