From b9b83edc1a2c74cca08353752bceba868bc9635f Mon Sep 17 00:00:00 2001 From: Nanda H Krishna Date: Mon, 3 May 2021 20:42:35 +0530 Subject: [PATCH 1/3] dev-cmd: rename `brew man` to `brew generate-man-completions` --- .github/workflows/update-manpage.yml | 2 +- Library/Homebrew/completions/bash.erb | 2 +- Library/Homebrew/completions/fish.erb | 2 +- Library/Homebrew/completions/zsh.erb | 2 +- .../dev-cmd/generate-man-completions.rb | 264 ++++++++++++++++++ Library/Homebrew/dev-cmd/man.rb | 244 +--------------- Library/Homebrew/manpages/brew.1.md.erb | 3 +- .../dev-cmd/generate-man-completions_spec.rb | 8 + manpages/README.md | 2 +- 9 files changed, 287 insertions(+), 242 deletions(-) create mode 100644 Library/Homebrew/dev-cmd/generate-man-completions.rb create mode 100644 Library/Homebrew/test/dev-cmd/generate-man-completions_spec.rb diff --git a/.github/workflows/update-manpage.yml b/.github/workflows/update-manpage.yml index 1ccbbcbce..b57ae9306 100644 --- a/.github/workflows/update-manpage.yml +++ b/.github/workflows/update-manpage.yml @@ -56,7 +56,7 @@ jobs: brew update-maintainers fi - if brew man --fail-if-not-changed; then + if brew generate-man-completions --fail-if-not-changed; then git add "$GITHUB_WORKSPACE/README.md" \ "$GITHUB_WORKSPACE/docs/Manpage.md" \ "$GITHUB_WORKSPACE/manpages/brew.1" \ diff --git a/Library/Homebrew/completions/bash.erb b/Library/Homebrew/completions/bash.erb index b10f89942..dfe77a08a 100644 --- a/Library/Homebrew/completions/bash.erb +++ b/Library/Homebrew/completions/bash.erb @@ -9,7 +9,7 @@ # compare with already documented commands. # - For other changes: Edit this file. # -# When done, regenerate the completions by running `brew man`. +# When done, regenerate the completions by running `brew generate-man-completions`. %> # Bash completion script for brew(1) diff --git a/Library/Homebrew/completions/fish.erb b/Library/Homebrew/completions/fish.erb index 6ba78a517..85b250379 100644 --- a/Library/Homebrew/completions/fish.erb +++ b/Library/Homebrew/completions/fish.erb @@ -9,7 +9,7 @@ # compare with already documented commands. # - For other changes: Edit this file. # -# When done, regenerate the completions by running `brew man`. +# When done, regenerate the completions by running `brew generate-man-completions`. %> # Fish shell completions for Homebrew diff --git a/Library/Homebrew/completions/zsh.erb b/Library/Homebrew/completions/zsh.erb index 7c202f1f6..1049d9f01 100644 --- a/Library/Homebrew/completions/zsh.erb +++ b/Library/Homebrew/completions/zsh.erb @@ -9,7 +9,7 @@ # compare with already documented commands. # - For other changes: Edit this file. # -# When done, regenerate the completions by running `brew man`. +# When done, regenerate the completions by running `brew generate-man-completions`. %> #compdef brew #autoload diff --git a/Library/Homebrew/dev-cmd/generate-man-completions.rb b/Library/Homebrew/dev-cmd/generate-man-completions.rb new file mode 100644 index 000000000..d5aebe4b7 --- /dev/null +++ b/Library/Homebrew/dev-cmd/generate-man-completions.rb @@ -0,0 +1,264 @@ +# typed: false +# frozen_string_literal: true + +require "formula" +require "erb" +require "ostruct" +require "cli/parser" +require "completions" + +module Homebrew + extend T::Sig + + module_function + + SOURCE_PATH = (HOMEBREW_LIBRARY_PATH/"manpages").freeze + TARGET_MAN_PATH = (HOMEBREW_REPOSITORY/"manpages").freeze + TARGET_DOC_PATH = (HOMEBREW_REPOSITORY/"docs").freeze + + sig { returns(CLI::Parser) } + def generate_man_completions_args + Homebrew::CLI::Parser.new do + description <<~EOS + Generate Homebrew's manpages. + EOS + switch "--fail-if-not-changed", + description: "Return a failing status code if no changes are detected in the manpage outputs. "\ + "This can be used to notify CI when the manpages are out of date. Additionally, "\ + "the date used in new manpages will match those in the existing manpages (to allow "\ + "comparison without factoring in the date)." + named_args :none + end + end + + def generate_man_completions + args = generate_man_completions_args.parse + + Commands.rebuild_internal_commands_completion_list + regenerate_man_pages(preserve_date: args.fail_if_not_changed?, quiet: args.quiet?) + Completions.update_shell_completions! + + diff = system_command "git", args: [ + "-C", HOMEBREW_REPOSITORY, "diff", "--exit-code", "docs/Manpage.md", "manpages", "completions" + ] + + return unless diff.status.success? + + puts "No changes to manpage or completions output detected." + Homebrew.failed = true if args.fail_if_not_changed? + end + + def regenerate_man_pages(preserve_date:, quiet:) + Homebrew.install_bundler_gems! + + markup = build_man_page(quiet: quiet) + convert_man_page(markup, TARGET_DOC_PATH/"Manpage.md", preserve_date: preserve_date) + markup = I18n.transliterate(markup, locale: :en) + convert_man_page(markup, TARGET_MAN_PATH/"brew.1", preserve_date: preserve_date) + end + + def build_man_page(quiet:) + template = (SOURCE_PATH/"brew.1.md.erb").read + variables = OpenStruct.new + + variables[:commands] = generate_cmd_manpages(Commands.internal_commands_paths) + variables[:developer_commands] = generate_cmd_manpages(Commands.internal_developer_commands_paths) + variables[:official_external_commands] = + generate_cmd_manpages(Commands.official_external_commands_paths(quiet: quiet)) + variables[:global_cask_options] = global_cask_options_manpage + variables[:global_options] = global_options_manpage + variables[:environment_variables] = env_vars_manpage + + readme = HOMEBREW_REPOSITORY/"README.md" + variables[:lead] = + readme.read[/(Homebrew's \[Project Leader.*\.)/, 1] + .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') + variables[:plc] = + readme.read[/(Homebrew's \[Project Leadership Committee.*\.)/, 1] + .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') + variables[:tsc] = + readme.read[/(Homebrew's \[Technical Steering Committee.*\.)/, 1] + .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') + variables[:linux] = + readme.read[/(Homebrew's Linux maintainers .*\.)/, 1] + .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') + variables[:maintainers] = + readme.read[/(Homebrew's other current maintainers .*\.)/, 1] + .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') + variables[:alumni] = + readme.read[/(Former maintainers .*\.)/, 1] + .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') + + ERB.new(template, trim_mode: ">").result(variables.instance_eval { binding }) + end + + def sort_key_for_path(path) + # Options after regular commands (`~` comes after `z` in ASCII table). + path.basename.to_s.sub(/\.(rb|sh)$/, "").sub(/^--/, "~~") + end + + def convert_man_page(markup, target, preserve_date:) + manual = target.basename(".1") + organisation = "Homebrew" + + # Set the manpage date to the existing one if we're checking for changes. + # This avoids the only change being e.g. a new date. + date = if preserve_date && target.extname == ".1" && target.exist? + /"(\d{1,2})" "([A-Z][a-z]+) (\d{4})" "#{organisation}" "#{manual}"/ =~ target.read + Date.parse("#{Regexp.last_match(1)} #{Regexp.last_match(2)} #{Regexp.last_match(3)}") + else + Date.today + end + date = date.strftime("%Y-%m-%d") + + shared_args = %W[ + --pipe + --organization=#{organisation} + --manual=#{target.basename(".1")} + --date=#{date} + ] + + format_flag, format_desc = target_path_to_format(target) + + puts "Writing #{format_desc} to #{target}" + Utils.popen(["ronn", format_flag] + shared_args, "rb+") do |ronn| + ronn.write markup + ronn.close_write + ronn_output = ronn.read + odie "Got no output from ronn!" if ronn_output.blank? + case format_flag + when "--markdown" + ronn_output = ronn_output.gsub(%r{(.*?)}, "*`\\1`*") + .gsub(/\n\n\n+/, "\n\n") + .gsub(/^(- `[^`]+`):/, "\\1") # drop trailing colons from definition lists + .gsub(/(?<=\n\n)([\[`].+):\n/, "\\1\n
") # replace colons with
on subcommands + when "--roff" + ronn_output = ronn_output.gsub(%r{(.*?)}, "\\fB\\1\\fR") + .gsub(%r{(.*?)}, "\\fI\\1\\fR") + .gsub(/(^\[?\\fB.+): /, "\\1\n ") + end + target.atomic_write ronn_output + end + end + + def target_path_to_format(target) + case target.basename + when /\.md$/ then ["--markdown", "markdown"] + when /\.\d$/ then ["--roff", "man page"] + else + odie "Failed to infer output format from '#{target.basename}'." + end + end + + def generate_cmd_manpages(cmd_paths) + man_page_lines = [] + + # preserve existing manpage order + cmd_paths.sort_by(&method(:sort_key_for_path)) + .each do |cmd_path| + cmd_man_page_lines = if (cmd_parser = CLI::Parser.from_cmd_path(cmd_path)) + next if cmd_parser.hide_from_man_page + + cmd_parser_manpage_lines(cmd_parser).join + else + cmd_comment_manpage_lines(cmd_path) + end + + man_page_lines << cmd_man_page_lines + end + + man_page_lines.compact.join("\n") + end + + def cmd_parser_manpage_lines(cmd_parser) + lines = [format_usage_banner(cmd_parser.usage_banner_text)] + lines += cmd_parser.processed_options.map do |short, long, _, desc| + if long.present? + next if Homebrew::CLI::Parser.global_options.include?([short, long, desc]) + next if Homebrew::CLI::Parser.global_cask_options.any? do |_, option, description:, **| + [long, "#{long}="].include?(option) && description == desc + end + end + + generate_option_doc(short, long, desc) + end.reject(&:blank?) + lines + end + + def cmd_comment_manpage_lines(cmd_path) + comment_lines = cmd_path.read.lines.grep(/^#:/) + return if comment_lines.empty? + return if comment_lines.first.include?("@hide_from_man_page") + + lines = [format_usage_banner(comment_lines.first).chomp] + comment_lines.slice(1..-1) + .each do |line| + line = line.slice(4..-2) + unless line + lines.last << "\n" + next + end + + # Omit the common global_options documented separately in the man page. + next if line.match?(/--(debug|help|quiet|verbose) /) + + # Format one option or a comma-separated pair of short and long options. + lines << line.gsub(/^ +(-+[a-z-]+), (-+[a-z-]+) +/, "* `\\1`, `\\2`:\n ") + .gsub(/^ +(-+[a-z-]+) +/, "* `\\1`:\n ") + end + lines.last << "\n" + lines + end + + sig { returns(String) } + def global_cask_options_manpage + lines = ["These options are applicable to the `install`, `reinstall`, and `upgrade` " \ + "subcommands with the `--cask` flag.\n"] + lines += Homebrew::CLI::Parser.global_cask_options.map do |_, long, description:, **| + generate_option_doc(nil, long.chomp("="), description) + end + lines.join("\n") + end + + sig { returns(String) } + def global_options_manpage + lines = ["These options are applicable across multiple subcommands.\n"] + lines += Homebrew::CLI::Parser.global_options.map do |short, long, desc| + generate_option_doc(short, long, desc) + end + lines.join("\n") + end + + sig { returns(String) } + def env_vars_manpage + lines = Homebrew::EnvConfig::ENVS.flat_map do |env, hash| + entry = "- `#{env}`:\n
#{hash[:description]}\n" + default = hash[:default_text] + default ||= "`#{hash[:default]}`." if hash[:default] + entry += "\n\n *Default:* #{default}\n" if default + + entry + end + lines.join("\n") + end + + def generate_option_doc(short, long, desc) + comma = (short && long) ? ", " : "" + <<~EOS + * #{format_short_opt(short)}#{comma}#{format_long_opt(long)}: + #{desc} + EOS + end + + def format_short_opt(opt) + "`#{opt}`" unless opt.nil? + end + + def format_long_opt(opt) + "`#{opt}`" unless opt.nil? + end + + def format_usage_banner(usage_banner) + usage_banner&.sub(/^(#: *\* )?/, "### ") + end +end diff --git a/Library/Homebrew/dev-cmd/man.rb b/Library/Homebrew/dev-cmd/man.rb index 22d65ede3..62655f4d9 100644 --- a/Library/Homebrew/dev-cmd/man.rb +++ b/Library/Homebrew/dev-cmd/man.rb @@ -1,21 +1,11 @@ # typed: false # frozen_string_literal: true -require "formula" -require "erb" -require "ostruct" -require "cli/parser" -require "completions" - module Homebrew extend T::Sig module_function - SOURCE_PATH = (HOMEBREW_LIBRARY_PATH/"manpages").freeze - TARGET_MAN_PATH = (HOMEBREW_REPOSITORY/"manpages").freeze - TARGET_DOC_PATH = (HOMEBREW_REPOSITORY/"docs").freeze - sig { returns(CLI::Parser) } def man_args Homebrew::CLI::Parser.new do @@ -28,237 +18,19 @@ module Homebrew "the date used in new manpages will match those in the existing manpages (to allow "\ "comparison without factoring in the date)." named_args :none + + hide_from_man_page! end end def man + odeprecated "`brew man`", "`brew generate-man-completions`" + args = man_args.parse + cmd = ["generate-man-completions"] + cmd << "--fail-if-not-changed" if args.fail_if_not_changed? - Commands.rebuild_internal_commands_completion_list - regenerate_man_pages(preserve_date: args.fail_if_not_changed?, quiet: args.quiet?) - Completions.update_shell_completions! - - diff = system_command "git", args: [ - "-C", HOMEBREW_REPOSITORY, "diff", "--exit-code", "docs/Manpage.md", "manpages", "completions" - ] - - return unless diff.status.success? - - puts "No changes to manpage or completions output detected." - Homebrew.failed = true if args.fail_if_not_changed? - end - - def regenerate_man_pages(preserve_date:, quiet:) - Homebrew.install_bundler_gems! - - markup = build_man_page(quiet: quiet) - convert_man_page(markup, TARGET_DOC_PATH/"Manpage.md", preserve_date: preserve_date) - markup = I18n.transliterate(markup, locale: :en) - convert_man_page(markup, TARGET_MAN_PATH/"brew.1", preserve_date: preserve_date) - end - - def build_man_page(quiet:) - template = (SOURCE_PATH/"brew.1.md.erb").read - variables = OpenStruct.new - - variables[:commands] = generate_cmd_manpages(Commands.internal_commands_paths) - variables[:developer_commands] = generate_cmd_manpages(Commands.internal_developer_commands_paths) - variables[:official_external_commands] = - generate_cmd_manpages(Commands.official_external_commands_paths(quiet: quiet)) - variables[:global_cask_options] = global_cask_options_manpage - variables[:global_options] = global_options_manpage - variables[:environment_variables] = env_vars_manpage - - readme = HOMEBREW_REPOSITORY/"README.md" - variables[:lead] = - readme.read[/(Homebrew's \[Project Leader.*\.)/, 1] - .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') - variables[:plc] = - readme.read[/(Homebrew's \[Project Leadership Committee.*\.)/, 1] - .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') - variables[:tsc] = - readme.read[/(Homebrew's \[Technical Steering Committee.*\.)/, 1] - .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') - variables[:linux] = - readme.read[/(Homebrew's Linux maintainers .*\.)/, 1] - .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') - variables[:maintainers] = - readme.read[/(Homebrew's other current maintainers .*\.)/, 1] - .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') - variables[:alumni] = - readme.read[/(Former maintainers .*\.)/, 1] - .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') - - ERB.new(template, trim_mode: ">").result(variables.instance_eval { binding }) - end - - def sort_key_for_path(path) - # Options after regular commands (`~` comes after `z` in ASCII table). - path.basename.to_s.sub(/\.(rb|sh)$/, "").sub(/^--/, "~~") - end - - def convert_man_page(markup, target, preserve_date:) - manual = target.basename(".1") - organisation = "Homebrew" - - # Set the manpage date to the existing one if we're checking for changes. - # This avoids the only change being e.g. a new date. - date = if preserve_date && target.extname == ".1" && target.exist? - /"(\d{1,2})" "([A-Z][a-z]+) (\d{4})" "#{organisation}" "#{manual}"/ =~ target.read - Date.parse("#{Regexp.last_match(1)} #{Regexp.last_match(2)} #{Regexp.last_match(3)}") - else - Date.today - end - date = date.strftime("%Y-%m-%d") - - shared_args = %W[ - --pipe - --organization=#{organisation} - --manual=#{target.basename(".1")} - --date=#{date} - ] - - format_flag, format_desc = target_path_to_format(target) - - puts "Writing #{format_desc} to #{target}" - Utils.popen(["ronn", format_flag] + shared_args, "rb+") do |ronn| - ronn.write markup - ronn.close_write - ronn_output = ronn.read - odie "Got no output from ronn!" if ronn_output.blank? - case format_flag - when "--markdown" - ronn_output = ronn_output.gsub(%r{(.*?)}, "*`\\1`*") - .gsub(/\n\n\n+/, "\n\n") - .gsub(/^(- `[^`]+`):/, "\\1") # drop trailing colons from definition lists - .gsub(/(?<=\n\n)([\[`].+):\n/, "\\1\n
") # replace colons with
on subcommands - when "--roff" - ronn_output = ronn_output.gsub(%r{(.*?)}, "\\fB\\1\\fR") - .gsub(%r{(.*?)}, "\\fI\\1\\fR") - .gsub(/(^\[?\\fB.+): /, "\\1\n ") - end - target.atomic_write ronn_output - end - end - - def target_path_to_format(target) - case target.basename - when /\.md$/ then ["--markdown", "markdown"] - when /\.\d$/ then ["--roff", "man page"] - else - odie "Failed to infer output format from '#{target.basename}'." - end - end - - def generate_cmd_manpages(cmd_paths) - man_page_lines = [] - - # preserve existing manpage order - cmd_paths.sort_by(&method(:sort_key_for_path)) - .each do |cmd_path| - cmd_man_page_lines = if (cmd_parser = CLI::Parser.from_cmd_path(cmd_path)) - next if cmd_parser.hide_from_man_page - - cmd_parser_manpage_lines(cmd_parser).join - else - cmd_comment_manpage_lines(cmd_path) - end - - man_page_lines << cmd_man_page_lines - end - - man_page_lines.compact.join("\n") - end - - def cmd_parser_manpage_lines(cmd_parser) - lines = [format_usage_banner(cmd_parser.usage_banner_text)] - lines += cmd_parser.processed_options.map do |short, long, _, desc| - if long.present? - next if Homebrew::CLI::Parser.global_options.include?([short, long, desc]) - next if Homebrew::CLI::Parser.global_cask_options.any? do |_, option, description:, **| - [long, "#{long}="].include?(option) && description == desc - end - end - - generate_option_doc(short, long, desc) - end.reject(&:blank?) - lines - end - - def cmd_comment_manpage_lines(cmd_path) - comment_lines = cmd_path.read.lines.grep(/^#:/) - return if comment_lines.empty? - return if comment_lines.first.include?("@hide_from_man_page") - - lines = [format_usage_banner(comment_lines.first).chomp] - comment_lines.slice(1..-1) - .each do |line| - line = line.slice(4..-2) - unless line - lines.last << "\n" - next - end - - # Omit the common global_options documented separately in the man page. - next if line.match?(/--(debug|help|quiet|verbose) /) - - # Format one option or a comma-separated pair of short and long options. - lines << line.gsub(/^ +(-+[a-z-]+), (-+[a-z-]+) +/, "* `\\1`, `\\2`:\n ") - .gsub(/^ +(-+[a-z-]+) +/, "* `\\1`:\n ") - end - lines.last << "\n" - lines - end - - sig { returns(String) } - def global_cask_options_manpage - lines = ["These options are applicable to the `install`, `reinstall`, and `upgrade` " \ - "subcommands with the `--cask` flag.\n"] - lines += Homebrew::CLI::Parser.global_cask_options.map do |_, long, description:, **| - generate_option_doc(nil, long.chomp("="), description) - end - lines.join("\n") - end - - sig { returns(String) } - def global_options_manpage - lines = ["These options are applicable across multiple subcommands.\n"] - lines += Homebrew::CLI::Parser.global_options.map do |short, long, desc| - generate_option_doc(short, long, desc) - end - lines.join("\n") - end - - sig { returns(String) } - def env_vars_manpage - lines = Homebrew::EnvConfig::ENVS.flat_map do |env, hash| - entry = "- `#{env}`:\n
#{hash[:description]}\n" - default = hash[:default_text] - default ||= "`#{hash[:default]}`." if hash[:default] - entry += "\n\n *Default:* #{default}\n" if default - - entry - end - lines.join("\n") - end - - def generate_option_doc(short, long, desc) - comma = (short && long) ? ", " : "" - <<~EOS - * #{format_short_opt(short)}#{comma}#{format_long_opt(long)}: - #{desc} - EOS - end - - def format_short_opt(opt) - "`#{opt}`" unless opt.nil? - end - - def format_long_opt(opt) - "`#{opt}`" unless opt.nil? - end - - def format_usage_banner(usage_banner) - usage_banner&.sub(/^(#: *\* )?/, "### ") + brew_rb = (HOMEBREW_LIBRARY_PATH/"brew.rb").resolved_path + system ENV["HOMEBREW_RUBY_PATH"], brew_rb, *cmd end end diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb index 194740e3f..a82cd8c2f 100644 --- a/Library/Homebrew/manpages/brew.1.md.erb +++ b/Library/Homebrew/manpages/brew.1.md.erb @@ -11,7 +11,8 @@ # - For environment variables: Edit `Library/Homebrew/env_config.rb`. # - For other changes: Edit this file. # -# When done, regenerate the man page and its HTML version by running `brew man`. +# When done, regenerate the man page and its HTML version by running +# `brew generate-man-completions`. %> brew(1) -- The Missing Package Manager for macOS (or Linux) =========================================================== diff --git a/Library/Homebrew/test/dev-cmd/generate-man-completions_spec.rb b/Library/Homebrew/test/dev-cmd/generate-man-completions_spec.rb new file mode 100644 index 000000000..91dc0f473 --- /dev/null +++ b/Library/Homebrew/test/dev-cmd/generate-man-completions_spec.rb @@ -0,0 +1,8 @@ +# typed: false +# frozen_string_literal: true + +require "cmd/shared_examples/args_parse" + +describe "brew generate-man-completions" do + it_behaves_like "parseable arguments" +end diff --git a/manpages/README.md b/manpages/README.md index 20e3cc744..40f815078 100644 --- a/manpages/README.md +++ b/manpages/README.md @@ -1,3 +1,3 @@ # Manual pages -This directory contains the generated Homebrew man pages from the `brew man` command. This command creates the output from the `CLI::Parser` definitions in files, sections extracted from the repository's `README.md` and `brew.1.md.erb`. +This directory contains the generated Homebrew man pages from the `brew generate-man-completions` command. This command creates the output from the `CLI::Parser` definitions in files, sections extracted from the repository's `README.md` and `brew.1.md.erb`. From 2aff9ef1e61a8bd04784021ca136eb33c1ee27d0 Mon Sep 17 00:00:00 2001 From: Nanda H Krishna Date: Tue, 4 May 2021 18:33:22 +0530 Subject: [PATCH 2/3] Update manpages and completions --- completions/bash/brew | 18 ++++++++++++++++++ completions/fish/brew.fish | 8 ++++++++ completions/internal_commands_list.txt | 1 + completions/zsh/_brew | 11 +++++++++++ docs/Manpage.md | 20 +++++++++++--------- manpages/brew.1 | 22 +++++++++++++--------- 6 files changed, 62 insertions(+), 18 deletions(-) diff --git a/completions/bash/brew b/completions/bash/brew index 07bb265f6..b742579ee 100644 --- a/completions/bash/brew +++ b/completions/bash/brew @@ -911,6 +911,23 @@ _brew_formula() { __brew_complete_formulae } +_brew_generate_man_completions() { + local cur="${COMP_WORDS[COMP_CWORD]}" + case "${cur}" in + -*) + __brewcomp " + --debug + --fail-if-not-changed + --help + --quiet + --verbose + " + return + ;; + *) + esac +} + _brew_gist_logs() { local cur="${COMP_WORDS[COMP_CWORD]}" case "${cur}" in @@ -2439,6 +2456,7 @@ _brew() { extract) _brew_extract ;; fetch) _brew_fetch ;; formula) _brew_formula ;; + generate-man-completions) _brew_generate_man_completions ;; gist-logs) _brew_gist_logs ;; home) _brew_home ;; homepage) _brew_homepage ;; diff --git a/completions/fish/brew.fish b/completions/fish/brew.fish index 383e6e61b..0c5dd4f48 100644 --- a/completions/fish/brew.fish +++ b/completions/fish/brew.fish @@ -671,6 +671,14 @@ __fish_brew_complete_arg 'formula' -l verbose -d 'Make some output more verbose' __fish_brew_complete_arg 'formula' -a '(__fish_brew_suggest_formulae_all)' +__fish_brew_complete_cmd 'generate-man-completions' 'Generate Homebrew\'s manpages' +__fish_brew_complete_arg 'generate-man-completions' -l debug -d 'Display any debugging information' +__fish_brew_complete_arg 'generate-man-completions' -l fail-if-not-changed -d 'Return a failing status code if no changes are detected in the manpage outputs. This can be used to notify CI when the manpages are out of date. Additionally, the date used in new manpages will match those in the existing manpages (to allow comparison without factoring in the date)' +__fish_brew_complete_arg 'generate-man-completions' -l help -d 'Show this message' +__fish_brew_complete_arg 'generate-man-completions' -l quiet -d 'Make some output more quiet' +__fish_brew_complete_arg 'generate-man-completions' -l verbose -d 'Make some output more verbose' + + __fish_brew_complete_cmd 'gist-logs' 'Upload logs for a failed build of formula to a new Gist' __fish_brew_complete_arg 'gist-logs' -l debug -d 'Display any debugging information' __fish_brew_complete_arg 'gist-logs' -l help -d 'Show this message' diff --git a/completions/internal_commands_list.txt b/completions/internal_commands_list.txt index 0b5931a16..b23578fc2 100644 --- a/completions/internal_commands_list.txt +++ b/completions/internal_commands_list.txt @@ -39,6 +39,7 @@ extract fetch formula formulae +generate-man-completions gist-logs help home diff --git a/completions/zsh/_brew b/completions/zsh/_brew index c0f710bae..4c45810c9 100644 --- a/completions/zsh/_brew +++ b/completions/zsh/_brew @@ -162,6 +162,7 @@ __brew_internal_commands() { 'fetch:Download a bottle (if available) or source packages for formulae and binaries for casks' 'formula:Display the path where formula is located' 'formulae:List all locally installable formulae including short names' + 'generate-man-completions:Generate Homebrew'\''s manpages' 'gist-logs:Upload logs for a failed build of formula to a new Gist' 'home:Open a formula or cask'\''s homepage in a browser, or open Homebrew'\''s own homepage if no argument is provided' 'info:Display brief statistics for your Homebrew installation' @@ -831,6 +832,16 @@ _brew_formula() { '*::formula:__brew_formulae' } +# brew generate-man-completions +_brew_generate_man_completions() { + _arguments \ + '--debug[Display any debugging information]' \ + '--fail-if-not-changed[Return a failing status code if no changes are detected in the manpage outputs. This can be used to notify CI when the manpages are out of date. Additionally, the date used in new manpages will match those in the existing manpages (to allow comparison without factoring in the date)]' \ + '--help[Show this message]' \ + '--quiet[Make some output more quiet]' \ + '--verbose[Make some output more verbose]' +} + # brew gist-logs _brew_gist_logs() { _arguments \ diff --git a/docs/Manpage.md b/docs/Manpage.md index 3c42e02c7..72c9c675d 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -1059,6 +1059,13 @@ a formula from a tap that is not `homebrew/core` use its fully-qualified form of Display the path where *`formula`* is located. +### `generate-man-completions` [*`--fail-if-not-changed`*] + +Generate Homebrew's manpages. + +* `--fail-if-not-changed`: + Return a failing status code if no changes are detected in the manpage outputs. This can be used to notify CI when the manpages are out of date. Additionally, the date used in new manpages will match those in the existing manpages (to allow comparison without factoring in the date). + ### `install-bundler-gems` Install Homebrew's Bundler gems. @@ -1111,13 +1118,6 @@ casks to check is taken from `HOMEBREW_LIVECHECK_WATCHLIST` or * `--cask`: Only check casks. -### `man` [*`--fail-if-not-changed`*] - -Generate Homebrew's manpages. - -* `--fail-if-not-changed`: - Return a failing status code if no changes are detected in the manpage outputs. This can be used to notify CI when the manpages are out of date. Additionally, the date used in new manpages will match those in the existing manpages (to allow comparison without factoring in the date). - ### `pr-automerge` [*`options`*] Find pull requests that can be automatically merged using `brew pr-publish`. @@ -1548,14 +1548,16 @@ to send a notification when the autoupdate process has finished successfully.
Prints the current status of this tool. `brew autoupdate version` -
Output this tool's current version. +
Output this tool's current version, and a short changelog. * `--upgrade`: Automatically upgrade your installed formulae. If the Caskroom exists locally Casks will be upgraded as well. Must be passed with `start`. * `--cleanup`: Automatically clean brew's cache and logs. Must be passed with `start`. * `--enable-notification`: - Send a notification when the autoupdate process has finished successfully, if `terminal-notifier` is installed & found. Note that currently a new experimental notifier runs automatically on macOS Big Sur, without requiring any external dependencies. Must be passed with `start`. + Send a notification when the autoupdate process has finished successfully, if `terminal-notifier` is installed & found. Note that currently a new experimental notifier runs automatically on macOS Catalina and newer, without requiring any external dependencies. Must be passed with `start`. +* `--immediate`: + Starts the autoupdate command immediately, instead of waiting for one interval (24 hours by default) to pass first. Must be passed with `start`. ### `bundle` [*`subcommand`*] diff --git a/manpages/brew.1 b/manpages/brew.1 index 8766af210..0ab308e46 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -1480,6 +1480,13 @@ Overwrite the destination formula if it already exists\. .SS "\fBformula\fR \fIformula\fR [\.\.\.]" Display the path where \fIformula\fR is located\. . +.SS "\fBgenerate\-man\-completions\fR [\fI\-\-fail\-if\-not\-changed\fR]" +Generate Homebrew\'s manpages\. +. +.TP +\fB\-\-fail\-if\-not\-changed\fR +Return a failing status code if no changes are detected in the manpage outputs\. This can be used to notify CI when the manpages are out of date\. Additionally, the date used in new manpages will match those in the existing manpages (to allow comparison without factoring in the date)\. +. .SS "\fBinstall\-bundler\-gems\fR" Install Homebrew\'s Bundler gems\. . @@ -1551,13 +1558,6 @@ Only check formulae\. \fB\-\-cask\fR Only check casks\. . -.SS "\fBman\fR [\fI\-\-fail\-if\-not\-changed\fR]" -Generate Homebrew\'s manpages\. -. -.TP -\fB\-\-fail\-if\-not\-changed\fR -Return a failing status code if no changes are detected in the manpage outputs\. This can be used to notify CI when the manpages are out of date\. Additionally, the date used in new manpages will match those in the existing manpages (to allow comparison without factoring in the date)\. -. .SS "\fBpr\-automerge\fR [\fIoptions\fR]" Find pull requests that can be automatically merged using \fBbrew pr\-publish\fR\. . @@ -2150,7 +2150,7 @@ This script will run \fBbrew update\fR in the background once every 24 hours (by . .P \fBbrew autoupdate version\fR - Output this tool\'s current version\. + Output this tool\'s current version, and a short changelog\. . .TP \fB\-\-upgrade\fR @@ -2162,7 +2162,11 @@ Automatically clean brew\'s cache and logs\. Must be passed with \fBstart\fR\. . .TP \fB\-\-enable\-notification\fR -Send a notification when the autoupdate process has finished successfully, if \fBterminal\-notifier\fR is installed & found\. Note that currently a new experimental notifier runs automatically on macOS Big Sur, without requiring any external dependencies\. Must be passed with \fBstart\fR\. +Send a notification when the autoupdate process has finished successfully, if \fBterminal\-notifier\fR is installed & found\. Note that currently a new experimental notifier runs automatically on macOS Catalina and newer, without requiring any external dependencies\. Must be passed with \fBstart\fR\. +. +.TP +\fB\-\-immediate\fR +Starts the autoupdate command immediately, instead of waiting for one interval (24 hours by default) to pass first\. Must be passed with \fBstart\fR\. . .SS "\fBbundle\fR [\fIsubcommand\fR]" Bundler for non\-Ruby dependencies from Homebrew, Homebrew Cask, Mac App Store and Whalebrew\. From ca11dc92ca33635afaa73d6d539fc2759c55cd53 Mon Sep 17 00:00:00 2001 From: Nanda H Krishna Date: Tue, 4 May 2021 18:38:55 +0530 Subject: [PATCH 3/3] `dev-cmd/generate-man-completions`: update description Co-authored-by: Rylan Polster --- Library/Homebrew/dev-cmd/generate-man-completions.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Library/Homebrew/dev-cmd/generate-man-completions.rb b/Library/Homebrew/dev-cmd/generate-man-completions.rb index d5aebe4b7..eaa6a2ad7 100644 --- a/Library/Homebrew/dev-cmd/generate-man-completions.rb +++ b/Library/Homebrew/dev-cmd/generate-man-completions.rb @@ -20,7 +20,7 @@ module Homebrew def generate_man_completions_args Homebrew::CLI::Parser.new do description <<~EOS - Generate Homebrew's manpages. + Generate Homebrew's manpages and shell completions. EOS switch "--fail-if-not-changed", description: "Return a failing status code if no changes are detected in the manpage outputs. "\