diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f666307ba6..fe0baadde7 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -32,7 +32,7 @@ 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 @@ -40,9 +40,10 @@ jobs: 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' diff --git a/docs/Adding-Software-to-Homebrew.md b/docs/Adding-Software-to-Homebrew.md index b097019e18..26418349ed 100644 --- a/docs/Adding-Software-to-Homebrew.md +++ b/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. diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index a449872225..f58fdb2a0c 100644 --- a/docs/Formula-Cookbook.md +++ b/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: diff --git a/docs/How-To-Organize-AGM.md b/docs/How-To-Organize-AGM.md index cca2a77fbe..a59ba15925 100644 --- a/docs/How-To-Organize-AGM.md +++ b/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 diff --git a/docs/Installation.md b/docs/Installation.md index 418a5013ca..eb25d59ccb 100644 --- a/docs/Installation.md +++ b/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). -1 For 32-bit or PPC support see [Tigerbrew](https://github.com/mistydemeo/tigerbrew). +1 For 32-bit or PPC support see [Tigerbrew](https://github.com/mistydemeo/tigerbrew). -2 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). +2 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). -3 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/). +3 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/). -4 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. +4 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. diff --git a/docs/Python-for-Formula-Authors.md b/docs/Python-for-Formula-Authors.md index 353f981f02..23a62fa544 100644 --- a/docs/Python-for-Formula-Authors.md +++ b/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: diff --git a/docs/Rakefile b/docs/Rakefile index e28c12460d..b0b6a9a5e4 100644 --- a/docs/Rakefile +++ b/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