sync/shared-config: sync docs, improve dependabot.

- the docs syncing should allow us to enforce a consistent structure
  for documentation across all our repositories.
- the dependabot syncing changes should avoid red CI and unnecessary
  dependabot checks in repositories missing the relevant files.

While we're here:
- use `yaml` consistently instead of `yml`

.github/actions/sync/shared-config.rb

@@ -24,22 +24,47 @@ def git(*args)
   abort "Usage: #{$PROGRAM_NAME} <target_directory_path> <homebrew_repository_path>"
 end
 
+docs = "docs"
 ruby_version = ".ruby-version"
-rubocop_yml = ".rubocop.yml"
-dependabot_yml = ".github/dependabot.yml"
+rubocop_yaml = ".rubocop.yml"
+dependabot_yaml = ".github/dependabot.yml"
+docs_workflow_yaml = ".github/workflows/docs.yml"
 
+homebrew_docs = homebrew_repository_path/docs
 homebrew_ruby_version =
   (homebrew_repository_path/"Library/Homebrew/vendor/portable-ruby-version").read
                                                                             .chomp
                                                                             .sub(/_\d+$/, "")
 homebrew_rubocop_config_yaml = YAML.load_file(
-  homebrew_repository_path/"Library/#{rubocop_yml}",
+  homebrew_repository_path/"Library/#{rubocop_yaml}",
   permitted_classes: [Symbol, Regexp],
 )
 homebrew_rubocop_config = homebrew_rubocop_config_yaml.reject do |key, _|
   key.match?(%r{\Arequire|inherit_from|inherit_mode|Cask/|Formula|Homebrew|Performance/|RSpec|Sorbet/})
 end.to_yaml
 
+dependabot_config_yaml = YAML.load_file(dependabot_yaml)
+dependabot_config_yaml["updates"].select! do |update|
+  case update["package-ecosystem"]
+  when "github-actions"
+    # every repository we sync to will have at least one workflow synced.
+    true
+  when "bundler"
+    (target_directory_path/"Gemfile.lock").exist?
+  when "npm"
+    (target_directory_path/"package.json").exist?
+  when "docker"
+    (target_directory_path/"Dockerfile").exist?
+  when "devcontainers"
+    (target_directory_path/".devcontainer/devcontainer.json").exist?
+  when "pip"
+    (target_directory_path/"requirements.txt").exist?
+  else
+    true
+  end
+end
+dependabot_config = dependabot_config_yaml.to_yaml
+
 custom_ruby_version_repos = %w[
   mass-bottling-tracker-private
 ].freeze
@@ -51,45 +76,63 @@ def git(*args)
 ].freeze
 custom_dependabot_repos = %w[
   brew
-  brew-pip-audit
   ci-orchestrator
 ].freeze
 
 puts "Detecting changes…"
 [
+  docs,
   ruby_version,
-  rubocop_yml,
-  dependabot_yml,
+  rubocop_yaml,
+  dependabot_yaml,
   ".github/workflows/lock-threads.yml",
   ".github/workflows/stale-issues.yml",
-].each do |file|
-  target_path = target_directory_path/file
+].each do |path|
+  target_path = target_directory_path/path
   target_path.dirname.mkpath
 
-  case file
+  case path
+  when docs
+    next if path == target_path.to_s
+    next unless target_path.exist?
+    next unless target_path.directory?
+
+    FileUtils.cp_r homebrew_docs, target_path.parent
+  when docs_workflow_yaml
+    next if path == target_path.to_s
+
+    docs_path = target_directory_path/docs
+    next unless docs_path.exist?
+    next unless docs_path.directory?
+
+    FileUtils.cp path, target_path
   when ruby_version
     next if custom_ruby_version_repos.include?(repository_name)
 
     target_path = target_directory_path/"Library/Homebrew/#{ruby_version}" if repository_name == "brew"
 
     target_path.write("#{homebrew_ruby_version}\n")
-  when rubocop_yml
+  when rubocop_yaml
     next if custom_rubocop_repos.include?(repository_name)
 
     FileUtils.rm_f target_path
     target_path.write(
       "# This file is synced from `Homebrew/brew` by the `.github` repository, do not modify it directly.\n" \
       "#{homebrew_rubocop_config}\n",
     )
-  when dependabot_yml
+  when dependabot_yaml
     next if custom_dependabot_repos.include?(repository_name)
-    next if file == target_path.to_s
+    next if path == target_path.to_s
 
-    FileUtils.cp file, target_path
+    FileUtils.rm_f target_path
+    target_path.write(
+      "# This file is synced from the `.github` repository, do not modify it directly.\n" \
+      "#{dependabot_config}\n",
+    )
   else
-    next if file == target_path.to_s
+    next if path == target_path.to_s
 
-    FileUtils.cp file, target_path
+    FileUtils.cp path, target_path
   end
 end