From 0fff6e0c09f2d1bdf9d1486b193840f0b1bc356e Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Wed, 30 Jan 2019 21:33:30 +0000 Subject: [PATCH] man: improve manpage output. --- Library/Homebrew/dev-cmd/man.rb | 89 +++++++++++++++------------------ 1 file changed, 40 insertions(+), 49 deletions(-) diff --git a/Library/Homebrew/dev-cmd/man.rb b/Library/Homebrew/dev-cmd/man.rb index 135081e227..c63b32857c 100644 --- a/Library/Homebrew/dev-cmd/man.rb +++ b/Library/Homebrew/dev-cmd/man.rb @@ -11,24 +11,8 @@ require "formula" require "erb" require "ostruct" require "cli_parser" -require "dev-cmd/audit" -require "dev-cmd/bottle" -require "dev-cmd/bump-formula-pr" -require "dev-cmd/create" -require "dev-cmd/edit" -require "dev-cmd/extract" -require "dev-cmd/formula" -require "dev-cmd/irb" -require "dev-cmd/linkage" -require "dev-cmd/mirror" -require "dev-cmd/prof" -require "dev-cmd/pull" -require "dev-cmd/release-notes" -require "dev-cmd/ruby" -require "dev-cmd/tap-new" -require "dev-cmd/test" -require "dev-cmd/tests" -require "dev-cmd/update-test" +# Require all commands +Dir.glob("#{HOMEBREW_LIBRARY_PATH}/{dev-,}cmd/*.rb").each { |cmd| require cmd } module Homebrew module_function @@ -83,22 +67,14 @@ module Homebrew convert_man_page(cask_markup, TARGET_MAN_PATH/"brew-cask.1") end - def path_glob_commands(glob) - Pathname.glob(glob) - .sort_by { |source_file| sort_key_for_path(source_file) } - .map(&:read).map(&:lines) - .map { |lines| lines.grep(/^#:/).map { |line| line.slice(2..-1) }.join } - .reject { |s| s.strip.empty? || s.include?("@hide_from_man_page") } - end - def build_man_page template = (SOURCE_PATH/"brew.1.md.erb").read variables = OpenStruct.new - variables[:commands] = path_glob_commands("#{HOMEBREW_LIBRARY_PATH}/cmd/*.{rb,sh}") + variables[:commands] = generate_cmd_manpages("#{HOMEBREW_LIBRARY_PATH}/cmd/*.{rb,sh}") + variables[:developer_commands] = generate_cmd_manpages("#{HOMEBREW_LIBRARY_PATH}/dev-cmd/{*.rb,sh}") + variables[:global_options] = global_options_manpage - variables[:developer_commands] = generate_cmd_manpages("#{HOMEBREW_LIBRARY_PATH}/dev-cmd/*.{rb,sh}") - variables[:global_options] = global_options_manpage_lines readme = HOMEBREW_REPOSITORY/"README.md" variables[:lead_maintainer] = readme.read[/(Homebrew's lead maintainer .*\.)/, 1] @@ -119,9 +95,6 @@ module Homebrew readme.read[/(Former maintainers .*\.)/, 1] .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') - variables[:homebrew_bundle] = help_output(:bundle) - variables[:homebrew_services] = help_output(:services) - ERB.new(template, nil, ">").result(variables.instance_eval { binding }) end @@ -162,6 +135,7 @@ module Homebrew odie "Got no output from ronn!" unless ronn_output if format_flag == "--markdown" ronn_output = ronn_output.gsub(%r{(.*?)}, "*`\\1`*") + .gsub(/\n\n\n+/, "\n\n") elsif format_flag == "--roff" ronn_output = ronn_output.gsub(%r{(.*?)}, "\\fB\\1\\fR") .gsub(%r{(.*?)}, "\\fI\\1\\fR") @@ -171,12 +145,6 @@ module Homebrew end end - def help_output(command) - tap = Tap.fetch("Homebrew/homebrew-#{command}") - tap.install unless tap.installed? - command_help_lines(which("brew-#{command}.rb", Tap.cmd_directories)) - end - def target_path_to_format(target) case target.basename when /\.md$/ then ["--markdown", "markdown"] @@ -190,38 +158,61 @@ module Homebrew cmd_paths = Pathname.glob(glob).sort man_page_lines = [] man_args = Homebrew.args - cmd_paths.each do |cmd_path| - begin - cmd_parser = Homebrew.send(cmd_arg_parser(cmd_path)) - man_page_lines << cmd_manpage_lines(cmd_parser).join - rescue NoMethodError - man_page_lines << path_glob_commands(cmd_path.to_s).first + # preserve existing manpage order + cmd_paths.sort_by(&method(:sort_key_for_path)) + .each do |cmd_path| + cmd_args_method_name = cmd_arg_parser(cmd_path) + + cmd_man_page_lines = begin + cmd_parser = Homebrew.send(cmd_args_method_name) + next if cmd_parser.hide_from_man_page + cmd_parser_manpage_lines(cmd_parser).join + rescue NoMethodError => e + raise if e.name != cmd_args_method_name + nil end + cmd_man_page_lines ||= cmd_comment_manpage_lines(cmd_path) + + man_page_lines << cmd_man_page_lines end Homebrew.args = man_args - man_page_lines + man_page_lines.compact.join("\n") end def cmd_arg_parser(cmd_path) "#{cmd_path.basename.to_s.gsub(".rb", "").tr("-", "_")}_args".to_sym end - def cmd_manpage_lines(cmd_parser) + 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| next if !long.nil? && cmd_parser.global_option?(cmd_parser.option_to_name(long)) 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..-1) + next unless line + lines << line.gsub(/^ +(-+[a-z-]+) */, "* `\\1`:\n ") end lines end - def global_options_manpage_lines + def global_options_manpage lines = ["These options are applicable across all sub-commands.\n"] lines += Homebrew::CLI::Parser.global_options.values.map do |names, _, desc| short, long = names generate_option_doc(short, long, desc) end - lines + lines.join("\n") end def generate_option_doc(short, long, desc) @@ -238,6 +229,6 @@ module Homebrew end def format_usage_banner(usage_banner) - usage_banner.sub(/^/, "### ") + usage_banner&.sub(/^(#: *\* )?/, "### ") end end