273 lines
9.1 KiB
Ruby
Raw Normal View History

2020-10-10 14:16:11 +02:00
# typed: false
# frozen_string_literal: true
require "formula"
require "erb"
require "ostruct"
2019-04-17 18:25:08 +09:00
require "cli/parser"
require "completions"
module Homebrew
2020-10-20 12:03:48 +02:00
extend T::Sig
2016-09-26 01:44:51 +02:00
module_function
2019-04-19 21:46:20 +09:00
SOURCE_PATH = (HOMEBREW_LIBRARY_PATH/"manpages").freeze
TARGET_MAN_PATH = (HOMEBREW_REPOSITORY/"manpages").freeze
TARGET_DOC_PATH = (HOMEBREW_REPOSITORY/"docs").freeze
2020-10-20 12:03:48 +02:00
sig { returns(CLI::Parser) }
def man_args
Homebrew::CLI::Parser.new do
description <<~EOS
2018-09-28 21:39:52 +05:30
Generate Homebrew's manpages.
2021-01-26 15:21:24 -05:00
*Note:* Not (yet) working on Apple Silicon.
2018-09-28 21:39:52 +05:30
EOS
switch "--fail-if-changed",
2019-04-30 08:44:35 +01:00
description: "Return a failing status code if changes are detected in the manpage outputs. This "\
"can be used to notify CI when the manpages are out of date. Additionally, "\
2019-04-30 08:44:35 +01:00
"the date used in new manpages will match those in the existing manpages (to allow "\
"comparison without factoring in the date)."
2021-01-10 14:26:40 -05:00
named_args :none
end
end
def man
# TODO: update description above if removing this.
if !ENV["HOMEBREW_SILICON_DEVELOPER"] && Hardware::CPU.arm?
raise UsageError, "not (yet) working on Apple Silicon!"
end
args = man_args.parse
2018-03-24 21:26:16 +05:30
Commands.rebuild_internal_commands_completion_list
regenerate_man_pages(preserve_date: args.fail_if_changed?, quiet: args.quiet?)
Completions.update_shell_completions!
2020-09-26 02:24:16 +02:00
diff = system_command "git", args: [
"-C", HOMEBREW_REPOSITORY, "diff", "--exit-code", "docs/Manpage.md", "manpages", "completions"
]
if diff.status.success?
puts "No changes to manpage or completions output detected."
elsif args.fail_if_changed?
2020-09-26 02:24:16 +02:00
puts "Changes to manpage or completions detected:"
puts diff.stdout
Homebrew.failed = true
end
end
def regenerate_man_pages(preserve_date:, quiet:)
Homebrew.install_bundler_gems!
markup = build_man_page(quiet: quiet)
2020-07-31 19:40:49 +02:00
convert_man_page(markup, TARGET_DOC_PATH/"Manpage.md", preserve_date: preserve_date)
convert_man_page(markup, TARGET_MAN_PATH/"brew.1", preserve_date: preserve_date)
end
def build_man_page(quiet:)
2016-09-05 21:46:40 +01:00
template = (SOURCE_PATH/"brew.1.md.erb").read
variables = OpenStruct.new
2021-01-25 09:18:10 +00:00
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
2019-01-30 21:33:30 +00:00
variables[:global_options] = global_options_manpage
variables[:environment_variables] = env_vars_manpage
2018-09-28 21:39:52 +05:30
readme = HOMEBREW_REPOSITORY/"README.md"
variables[:lead] =
2019-02-15 10:54:30 +00:00
readme.read[/(Homebrew's \[Project Leader.*\.)/, 1]
.gsub(/\[([^\]]+)\]\([^)]+\)/, '\1')
variables[:plc] =
2019-02-15 10:54:30 +00:00
readme.read[/(Homebrew's \[Project Leadership Committee.*\.)/, 1]
.gsub(/\[([^\]]+)\]\([^)]+\)/, '\1')
variables[:tsc] =
2019-02-15 10:54:30 +00:00
readme.read[/(Homebrew's \[Technical Steering Committee.*\.)/, 1]
.gsub(/\[([^\]]+)\]\([^)]+\)/, '\1')
variables[:linux] =
readme.read[%r{(Homebrew/brew'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')
2016-06-14 21:01:50 +08:00
2019-10-13 10:09:38 +01:00
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
2020-07-31 19:40:49 +02:00
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.
2020-07-31 19:40:49 +02:00
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
2019-10-08 10:49:02 +01:00
odie "Got no output from ronn!" if ronn_output.blank?
2020-07-13 22:48:53 +10:00
case format_flag
when "--markdown"
ronn_output = ronn_output.gsub(%r{<var>(.*?)</var>}, "*`\\1`*")
2019-01-30 21:33:30 +00:00
.gsub(/\n\n\n+/, "\n\n")
.gsub(/^(- `[^`]+`):/, "\\1") # drop trailing colons from definition lists
.gsub(/(?<=\n\n)([\[`].+):\n/, "\\1\n<br>") # replace colons with <br> on subcommands
2020-07-13 22:48:53 +10:00
when "--roff"
2018-10-03 10:19:46 +05:30
ronn_output = ronn_output.gsub(%r{<code>(.*?)</code>}, "\\fB\\1\\fR")
.gsub(%r{<var>(.*?)</var>}, "\\fI\\1\\fR")
.gsub(/(^\[?\\fB.+): /, "\\1\n ")
2018-10-02 19:54:22 +05:30
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
2018-09-08 22:21:04 +05:30
def generate_cmd_manpages(cmd_paths)
2018-09-28 21:39:52 +05:30
man_page_lines = []
2019-01-30 21:33:30 +00:00
# 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)
2019-01-30 21:33:30 +00:00
next if cmd_parser.hide_from_man_page
2019-01-30 21:33:30 +00:00
cmd_parser_manpage_lines(cmd_parser).join
else
cmd_comment_manpage_lines(cmd_path)
2018-09-28 21:39:52 +05:30
end
2019-01-30 21:33:30 +00:00
man_page_lines << cmd_man_page_lines
2018-09-28 21:39:52 +05:30
end
2019-01-30 21:33:30 +00:00
man_page_lines.compact.join("\n")
2018-09-28 21:39:52 +05:30
end
2019-01-30 21:33:30 +00:00
def cmd_parser_manpage_lines(cmd_parser)
2018-10-02 19:54:22 +05:30
lines = [format_usage_banner(cmd_parser.usage_banner_text)]
2018-09-08 22:21:04 +05:30
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)
2019-01-30 21:33:30 +00:00
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")
2019-01-30 21:33:30 +00:00
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.
2020-07-30 18:40:10 +02:00
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
2020-10-20 12:03:48 +02:00
sig { returns(String) }
def global_cask_options_manpage
2020-12-30 15:09:00 -05:00
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:, **|
2020-11-12 10:40:41 -05:00
generate_option_doc(nil, long.chomp("="), description)
end
lines.join("\n")
end
2020-10-20 12:03:48 +02:00
sig { returns(String) }
2019-01-30 21:33:30 +00:00
def global_options_manpage
lines = ["These options are applicable across multiple subcommands.\n"]
2020-07-30 18:40:10 +02:00
lines += Homebrew::CLI::Parser.global_options.map do |short, long, desc|
2018-09-08 22:21:04 +05:30
generate_option_doc(short, long, desc)
end
2019-01-30 21:33:30 +00:00
lines.join("\n")
2018-09-08 22:21:04 +05:30
end
2020-10-20 12:03:48 +02:00
sig { returns(String) }
def env_vars_manpage
lines = Homebrew::EnvConfig::ENVS.flat_map do |env, hash|
entry = "- `#{env}`:\n <br>#{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
2018-09-08 22:21:04 +05:30
def generate_option_doc(short, long, desc)
comma = (short && long) ? ", " : ""
<<~EOS
* #{format_short_opt(short)}#{comma}#{format_long_opt(long)}:
#{desc}
EOS
2018-09-08 22:21:04 +05:30
end
def format_short_opt(opt)
"`#{opt}`" unless opt.nil?
2018-09-08 22:21:04 +05:30
end
def format_long_opt(opt)
"`#{opt}`" unless opt.nil?
2018-09-08 22:21:04 +05:30
end
def format_usage_banner(usage_banner)
2019-01-30 21:33:30 +00:00
usage_banner&.sub(/^(#: *\* )?/, "### ")
end
end