Synchronize shared configuration

.github/dependabot.yml

@@ -1,53 +1,24 @@
 # This file is synced from the `.github` repository, do not modify it directly.
+---
 version: 2
-
 updates:
-  - package-ecosystem: github-actions
-    directory: /
-    schedule:
-      interval: daily
-    allow:
-      - dependency-type: all
-    # The actions in triage-issues.yml are updated in the Homebrew/.github repo
-    ignore:
-      - dependency-name: actions/stale
-      - dependency-name: dessant/lock-threads
-    groups:
-      artifacts:
-        patterns:
-          - actions/*-artifact
-
-  - package-ecosystem: bundler
-    directory: /
-    schedule:
-      interval: daily
-    allow:
-      - dependency-type: all
-
-  - package-ecosystem: npm
-    directory: /
-    schedule:
-      interval: daily
-    allow:
-      - dependency-type: all
-
-  - package-ecosystem: docker
-    directory: /
-    schedule:
-      interval: daily
-    allow:
-      - dependency-type: all
-
-  - package-ecosystem: devcontainers
-    directory: /
-    schedule:
-      interval: daily
-    allow:
-      - dependency-type: all
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: daily
+  allow:
+  - dependency-type: all
+  ignore:
+  - dependency-name: actions/stale
+  - dependency-name: dessant/lock-threads
+  groups:
+    artifacts:
+      patterns:
+      - actions/*-artifact
+- package-ecosystem: bundler
+  directory: "/"
+  schedule:
+    interval: daily
+  allow:
+  - dependency-type: all
 
-  - package-ecosystem: pip
-    directory: /
-    schedule:
-      interval: daily
-    allow:
-      - dependency-type: all

.github/workflows/docs.yml

@@ -0,0 +1,74 @@
+name: Documentation CI
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  HOMEBREW_DEVELOPER: 1
+  HOMEBREW_NO_AUTO_UPDATE: 1
+  HOMEBREW_NO_ENV_HINTS: 1
+  HOMEBREW_BOOTSNAP: 1
+  HOMEBREW_NO_INSTALL_CLEANUP: 1
+
+jobs:
+  docs:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Set up Homebrew
+        id: set-up-homebrew
+        uses: Homebrew/actions/setup-homebrew@master
+        with:
+          core: false
+          cask: false
+          test-bot: false
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install vale
+        run: brew install vale
+
+      - name: Cleanup Homebrew/brew docs
+        if: github.repository == 'Homebrew/brew'
+        run: |
+          set -xeuo pipefail
+
+          # Avoid failing on broken symlinks.
+          rm Library/Homebrew/os/mac/pkgconfig/fuse/fuse.pc
+          rm Library/Homebrew/os/mac/pkgconfig/fuse/osxfuse.pc
+
+          # No ignore support (https://github.com/errata-ai/vale/issues/131).
+          rm -r Library/Homebrew/vendor
+
+      - name: Run Vale
+        run: vale docs/
+
+      - name: Install Ruby
+        uses: ruby/setup-ruby@78c01b705fd9d5ad960d432d3a0cfa341d50e410 # v1.179.1
+        with:
+          bundler-cache: true
+          working-directory: docs
+
+      - name: Check Markdown syntax
+        working-directory: docs
+        run: bundle exec rake lint
+
+      - name: Check code blocks conform to our Ruby style guide
+        run: brew style docs
+
+      - name: Generate formulae.brew.sh API samples
+        if: github.repository == 'Homebrew/formulae.brew.sh'
+        working-directory: docs
+        run: ../script/generate-api-samples.rb
+
+      - name: Build the site and check for broken links
+        working-directory: docs
+        run: bundle exec rake test
+        env:
+          JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -13,5 +13,8 @@ api/cask-source/
 api/cask/
 api/formula/
 api/internal/
+docs/_includes/api-samples/
+docs/tmp/
+docs/Gemfile.lock
 cask/
 formula/

.vale.ini

@@ -0,0 +1,7 @@
+StylesPath = ./docs/vale-styles
+
+[formats]
+rb = md
+
+[*.{md,rb}]
+BasedOnStyles = Homebrew

docs/.mdl_ruleset.rb

@@ -0,0 +1,7 @@
+rule 'HB034', 'Bare unstyled URL used' do
+  tags :links, :url
+  aliases 'no-bare-unstyled-urls'
+  check do |doc|
+    doc.matching_text_element_lines(%r{(?<=\s)https?://})
+  end
+end

docs/.mdl_style.rb

@@ -0,0 +1,8 @@
+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
+exclude_rule 'MD033' # Inline HTML
+exclude_rule 'MD034' # Bare URL used (replaced by HB034)
+exclude_rule 'MD046' # Code block style

docs/.mdlrc

@@ -0,0 +1,4 @@
+git_recurse true
+ignore_front_matter true
+style "#{File.dirname(__FILE__)}/.mdl_style.rb"
+rulesets ["#{File.dirname(__FILE__)}/.mdl_ruleset.rb"]

docs/.rubocop.yml

@@ -0,0 +1,32 @@
+inherit_from: ../Library/.rubocop.yml
+
+AllCops:
+  Exclude:
+  - Gemfile
+  - ".mdl*.rb"
+  - Rakefile
+  - "_site/**/*"
+  - Manpage.md
+
+# These are included in docs deliberately to show what
+# `brew create` does and what the user should replace.
+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.
+
+# 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/.ruby-version

@@ -0,0 +1 @@
+3.3.2

docs/Gemfile

@@ -0,0 +1,12 @@
+source "https://rubygems.org"
+
+ruby file: ".ruby-version"
+
+gem "github-pages", group: :jekyll_plugins
+
+group :test do
+  gem "html-proofer"
+  gem "mdl"
+  gem "rake"
+  gem "webrick"
+end

docs/Rakefile

@@ -0,0 +1,43 @@
+require "rake"
+
+task default: :build
+
+desc "Build the site."
+task :build do
+  sh "jekyll", "build"
+end
+
+desc "Run Markdownlint to validate the Markdown style."
+task :lint do
+  sh "mdl $(git ls-files '*.md' | grep -v 'Manpage.md')"
+end
+
+desc "Run HTMLProofer to validate the HTML output."
+task test: :build do
+  require "html-proofer"
+  HTMLProofer.check_directory(
+    "./_site",
+    parallel: { in_threads: 4 },
+    favicon: true,
+    ignore_status_codes: [0, 403],
+    check_favicon: true,
+    check_opengraph: true,
+    check_html: true,
+    check_img_http: true,
+    enforce_https: true,
+    ignore_files: [
+      %r{Kickstarter-Supporters},
+    ],
+    ignore_urls: [
+      "/",
+      %r{https://formulae.brew.sh"},
+      %r{https://github.com/},
+      'https://legacy.python.org/dev/peps/pep-0453/#recommendations-for-downstream-distributors',
+    ],
+    cache: {
+      timeframe: {
+        external: "1h"
+      }
+    }
+  ).run
+end