CI: add docs.yml

With fixes for Markdown syntax to allow tests to pass.

.github/workflows/docs.yml

@@ -0,0 +1,67 @@
+name: Documentation CI
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  linting:
+   if: github.repository == 'Homebrew/brew'
+    runs-on: ubuntu-22.04
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Set up Homebrew
+        id: set-up-homebrew
+        uses: Homebrew/actions/setup-homebrew@master
+
+      - name: Install vale
+        run: brew install vale
+
+      - name: Run vale for docs linting
+        run: vale .
+
+      - name: Install Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "2.7"
+          bundler-cache: true
+          working-directory: docs
+
+      - name: Check Markdown syntax
+        run: bundle exec rake lint
+
+      - name: Build docs site
+        run: bundle exec rake build
+
+  rubydoc:
+   if: github.repository == 'Homebrew/brew'
+    runs-on: ubuntu-22.04
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/rubydoc/Gemfile
+    steps:
+      - name: Set up Homebrew
+        id: set-up-homebrew
+        uses: Homebrew/actions/setup-homebrew@master
+
+      - name: Checkout Homebrew/rubydoc.brew.sh
+        uses: actions/checkout@main
+        with:
+          repository: Homebrew/rubydoc.brew.sh
+          path: rubydoc
+
+      - name: Install Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "2.7"
+          bundler-cache: true
+
+      - name: Process rubydoc comments
+        working-directory: Library/Homebrew
+        run: bundle exec yard doc --plugin sorbet --no-output #--fail-on-warning

.github/workflows/tests.yml

@@ -37,18 +37,13 @@ jobs:
       - name: Install Bundler RubyGems
         run: brew install-bundler-gems --groups=sorbet
 
-      - name: Install shellcheck
-        run: brew install shellcheck
+      - name: Install shellcheck and shfmt
+        run: brew install shellcheck shfmt
 
       - run: brew style --display-cop-names
 
       - run: brew typecheck
 
-      - name: Run vale for docs linting
-        run: |
-          brew install vale
-          vale docs/
-
   tap-syntax:
     name: tap syntax
     needs: syntax
@@ -282,6 +277,7 @@ jobs:
 
   test-default-formula-linux:
     name: ${{ matrix.name }}
+    if: startsWith(github.repository, 'Homebrew/')
     runs-on: ${{ matrix.runs-on }}
     env:
       HOMEBREW_BOOTSNAP: 1

docs/.mdl_style.rb

@@ -1,4 +1,5 @@
 all
+rule 'MD007', indent: 2 # Unordered list indentation
 rule 'MD026', punctuation: ',;:' # Trailing punctuation in header
 exclude_rule 'MD013' # Line length
 exclude_rule 'MD029' # Ordered list item prefix

docs/Adding-Software-to-Homebrew.md

@@ -178,7 +178,7 @@ Other commonly used stanzas are:
 | ------------------ | ----------- |
 | `livecheck`        | Ruby block describing how to find updates for this cask (see [`livecheck` Stanza Details](Cask-Cookbook.md#stanza-livecheck))
 | `pkg`              | relative path to a `.pkg` file containing the distribution (see [`pkg` Stanza Details](Cask-Cookbook.md#stanza-pkg))
-| `caveats`          | a string or Ruby block providing the user with cask-specific information at install time (see [`caveats` Stanza Details](Cask-Cookbook.md#stanza-caveats))
+| `caveats`          | string or Ruby block providing the user with cask-specific information at install time (see [`caveats` Stanza Details](Cask-Cookbook.md#stanza-caveats))
 | `uninstall`        | procedures to uninstall a cask; optional unless the `pkg` stanza is used (see [`uninstall` Stanza Details](Cask-Cookbook.md#stanza-uninstall))
 | `zap`              | additional procedures for a more complete uninstall, including configuration files and shared resources (see [`zap` Stanza Details](Cask-Cookbook.md#stanza-zap))
 

docs/Brew-Test-Bot.md

@@ -32,4 +32,3 @@ A passed build looks like this:
 ---
 
 On failed or passed builds you can click the "Details" link to view the result in GitHub Actions.
-

docs/Common-Issues-for-Core-Contributors.md

@@ -9,10 +9,12 @@ This is a page for maintainers to diagnose certain build errors.
 ### Bottle publishes failed but the commits are correct in the git history
 
 Follow these steps to fix this issue:
+
 * Download and extract the bottle artifact.
 * `brew pr-upload --no-commit` in the bottle directory.
 
 Alternative instructions using `pr-pull`:
+
 * `git reset --hard <SHA>` in homebrew/core to reset to the commit before before all the commits created by `brew pr-pull`.
 * `brew pr-pull <options>` to upload the right bottles. Add the `--warn-on-upload-failure` flag if the bottles have been partially uploaded and you're certain that the bottle checksums will match the checksums already present in the `bottle do` block of the formula.
 * `git reset --hard origin/master` to return to the latest commit and discard the commits made by `brew pr-pull`.
@@ -21,5 +23,4 @@ Alternative instructions using `pr-pull`:
 
 The exact atom may be different.
 
-This can be caused by passing the obsolete `-s` flag to the linker and can be
-fixed like [this](https://github.com/Homebrew/homebrew-core/commit/c4ad981d788b21a406a6efe7748f2922986919a8).
+This can be caused by passing the obsolete `-s` flag to the linker and can be fixed like [this](https://github.com/Homebrew/homebrew-core/commit/c4ad981d788b21a406a6efe7748f2922986919a8).

docs/Deprecating-Disabling-and-Removing-Formulae.md

@@ -49,7 +49,7 @@ The most common reasons for disabling a formula are:
 
 Formulae should not be disabled without a deprecation period of at least three months unless the circumstances are exceptional (e.g. the formula does not build on any supported macOS version or Linux). Popular formulae should have longer deprecation periods. The popularity of a formula should be based on our analytics data.
 
-**Note: disabled formulae in `homebrew/core` will be automatically removed one year after their disable date**.
+**Note: disabled formulae in `homebrew/core` will be automatically removed one year after their disable date.**
 
 To disable a formula, add a `disable!` call. This call should include a deprecation date (in the ISO 8601 format) and a deprecation reason:
 

docs/Homebrew-Governance-Archives.md

@@ -1,7 +1,8 @@
 # Homebrew Governance Archives
 
 {% assign governance_pages = site.pages | where: "category", "governance-archives" %}
+{% assign marker = "-" %}
 
 {% for item in governance_pages -%}
-- [{{ item.title }}]({{ item.url }})
+{{ marker }} [{{ item.title }}]({{ item.url }})
 {% endfor %}

docs/Homebrew-Leadership-Responsibilities.md

@@ -21,16 +21,16 @@
 
 - January: check membership, announce AGM votes
   - Ask for nominations for the for the PLC and project leader, and ask who is interested in serving on the TSC
-  - Create ballots for the elections on https://www.opavote.com
+  - Create ballots for the elections on <https://www.opavote.com>
   - Ask the project leader and representatives of the PLC and TSC to prepare reports for the AGM
   - Ask for members interested in presenting lightning talks at the AGM
 - February: organise the annual general meeting (AGM)
   - Create a dedicated Slack channel
   - Book a group dinner (which Homebrew pays for) and check for any dietary requirements
   - Ask someone to bring a conference/table microphone for people to be able to remotely participate in AGM
 - February after the AGM:
-  - Add the minutes of the AGM to https://github.com/Homebrew/homebrew-governance
-  - Create [issue in homebrew-governance](https://github.com/homebrew/homebrew-governance/issues) to ask members who did not vote in the election whether they wish to remain or step down as members
+  - Add the minutes of the AGM to <https://github.com/Homebrew/brew/tree/master/docs/governance>
+  - Create [issue in Homebrew/brew](https://github.com/Homebrew/brew/issues?q=is%3Aissue+in%3Atitle+membership+) to ask members who did not vote in the election whether they wish to remain or step down as members
     - Members that are not maintainers should be a least one of:
       - An current or previously active maintainer, PLC/TSC member or Project Leader
       - A long-standing member of the Homebrew community (e.g. been submitting good bug reports for over two years)

docs/Homebrew-and-Python.md

@@ -87,10 +87,9 @@ CFLAGS="-I$(brew --prefix)/include" LDFLAGS="-L$(brew --prefix)/lib" pip install
 
 ## Virtualenv
 
-**Warning!** When you `brew install` formulae that provide Python bindings, you should **not be in an active virtual environment**.
+**Warning!** When you `brew install` formulae that provide Python bindings, you should **not be in an active virtual environment.**
 
-Activate the virtualenv *after* you've brewed, or brew in a fresh terminal window.
-This will ensure Python modules are installed into Homebrew's `site-packages` and *not* into that of the virtual environment.
+Activate the virtualenv *after* you've brewed, or brew in a fresh terminal window. This will ensure Python modules are installed into Homebrew's `site-packages` and *not* into that of the virtual environment.
 
 Virtualenv has a `--system-site-packages` switch to allow "global" (i.e. Homebrew's) `site-packages` to be accessible from within the virtualenv.
 

docs/Homebrew-homebrew-core-Maintainer-Guide.md

@@ -13,8 +13,7 @@ A detailed checklist can be found [below](#detailed-merge-checklist). This is al
   [pip](https://pip.pypa.io/en/stable/).
 - Ensure that any dependencies are accurate and minimal. We don't need to
   support every possible optional feature for the software.
-- When bottles aren't required or affected, use the GitHub squash & merge workflow for a single-formula PR or rebase & merge workflow for a multiple-formulae PR. See the ["How to merge without bottles" section below](#how-to-merge-without-bottles)
-for more details.
+- When bottles aren't required or affected, use the GitHub squash & merge workflow for a single-formula PR or rebase & merge workflow for a multiple-formulae PR. See the ["How to merge without bottles" section below](#how-to-merge-without-bottles) for more details.
 - Use `brew pr-publish` or `brew pr-pull` otherwise, which adds messages to auto-close pull requests and pull bottles built by the Brew Test Bot.
 - Thank people for contributing.
 
@@ -155,18 +154,18 @@ transparency for contributors in addition to the
 - bottle block is not removed
 
   Suggested reply:
-  ```
-  Please keep bottle block in place, [@BrewTestBot](https://github.com/BrewTestBot) takes care of it.
-  ```
+
+      Please keep bottle block in place; [@BrewTestBot](https://github.com/BrewTestBot) takes care of it.
+
 - is there a test block for other than checking version or printing help? Consider asking to add one
 - if CI failed
   - due to test block - paste relevant lines and add `test failure` label
   - due to build errors - paste relevant lines and add `build failure` label
   - due to other formulae needing revision bumps - suggest to use the following command:
-    ```
-    # in this example PR is for `libuv` formula and `urbit` needs revision bump
-    brew bump-revision --message 'for libuv' urbit
-    ```
+
+        # in this example: PR is for `libuv` formula and `urbit` needs revision bump
+        brew bump-revision --message 'for libuv' urbit
+
     - make sure it is one commit per revision bump
 - if CI is green and...
   - bottles need to be pulled, and...
@@ -187,16 +186,14 @@ This error might pop up when parameters passed to `gcc` are in the wrong order.
 
 An example from `libmagic` formula:
 
-```
-==> brew test libmagic --verbose
-Testing libmagic
-==> /usr/bin/gcc -I/home/linuxbrew/.linuxbrew/Cellar/libmagic/5.38/include -L/home/linuxbrew/.linuxbrew/Cellar/libmagic/5.38/lib -lmagic test.c -o test
-/tmp/ccNeDVRt.o: In function `main':
-test.c:(.text+0x15): undefined reference to `magic_open'
-test.c:(.text+0x4a): undefined reference to `magic_load'
-test.c:(.text+0x81): undefined reference to `magic_file'
-collect2: error: ld returned 1 exit status
-```
+    ==> brew test libmagic --verbose
+    Testing libmagic
+    ==> /usr/bin/gcc -I/home/linuxbrew/.linuxbrew/Cellar/libmagic/5.38/include -L/home/linuxbrew/.linuxbrew/Cellar/libmagic/5.38/lib -lmagic test.c -o test
+    /tmp/ccNeDVRt.o: In function `main':
+    test.c:(.text+0x15): undefined reference to `magic_open'
+    test.c:(.text+0x4a): undefined reference to `magic_load'
+    test.c:(.text+0x81): undefined reference to `magic_file'
+    collect2: error: ld returned 1 exit status
 
 Solution:
 

docs/Maintainers-Avoiding-Burnout.md

@@ -46,4 +46,4 @@ work to be done.
 
 ---
 
-_Thanks to https://gist.github.com/ryanflorence/124070e7c4b3839d4573 which influenced this document_
+_Thanks to <https://gist.github.com/ryanflorence/124070e7c4b3839d4573> which influenced this document._

docs/Rakefile

@@ -8,8 +8,8 @@ task :build do
 end
 
 desc "Run Markdownlint to validate the Markdown style."
-task lint: :build do
-  sh "mdl", "."
+task :lint do
+  sh "mdl $(git ls-files '*.md' | grep -v 'Manpage.md')"
 end
 
 desc "Run HTMLProofer to validate the HTML output."

docs/governance/2021-agm-minutes.md

@@ -31,7 +31,6 @@
   Jonathan Chang and Issy Long are elected.
 
   <https://www.opavote.com/results/5937355983683584>
-
 - 11:57–12:00 Election of the Project Leader
 
   Mike McQuaid elected by acclamation.
@@ -49,7 +48,7 @@
 - 12:55–13:00 Shaun Jackman - Speeding up install times / Git repo size <https://github.com/Homebrew/install/issues/523>
 - 13:10 Meeting adjourned
 
-## Motions
+## Resolutions
 
 ### Motion to adopt the voting system
 

docs/vale-styles/Homebrew/README.md

@@ -1 +1,3 @@
+# Vale Styles
+
 Based on Homebrew's [Prose Style Guidelines](http://docs.brew.sh/Prose-Style-Guidelines.html).