docspring 3.0.0 → 3.1.0

data/vendor/bundle/ruby/3.3.0/gems/rdoc-6.12.0/lib/rdoc/options.rb

@@ -0,0 +1,1397 @@
+# frozen_string_literal: true
+require 'optparse'
+require 'pathname'
+
+##
+# RDoc::Options handles the parsing and storage of options
+#
+# == Saved Options
+#
+# You can save some options like the markup format in the
+# <tt>.rdoc_options</tt> file in your gem.  The easiest way to do this is:
+#
+#   rdoc --markup tomdoc --write-options
+#
+# Which will automatically create the file and fill it with the options you
+# specified.
+#
+# The following options will not be saved since they interfere with the user's
+# preferences or with the normal operation of RDoc:
+#
+# * +--coverage-report+
+# * +--dry-run+
+# * +--encoding+
+# * +--force-update+
+# * +--format+
+# * +--pipe+
+# * +--quiet+
+# * +--template+
+# * +--verbose+
+#
+# == Custom Options
+#
+# Generators can hook into RDoc::Options to add generator-specific command
+# line options.
+#
+# When <tt>--format</tt> is encountered in ARGV, RDoc calls ::setup_options on
+# the generator class to add extra options to the option parser.  Options for
+# custom generators must occur after <tt>--format</tt>.  <tt>rdoc --help</tt>
+# will list options for all installed generators.
+#
+# Example:
+#
+#   class RDoc::Generator::Spellcheck
+#     RDoc::RDoc.add_generator self
+#
+#     def self.setup_options rdoc_options
+#       op = rdoc_options.option_parser
+#
+#       op.on('--spell-dictionary DICTIONARY',
+#             RDoc::Options::Path) do |dictionary|
+#         rdoc_options.spell_dictionary = dictionary
+#       end
+#     end
+#   end
+#
+# Of course, RDoc::Options does not respond to +spell_dictionary+ by default
+# so you will need to add it:
+#
+#   class RDoc::Options
+#
+#     ##
+#     # The spell dictionary used by the spell-checking plugin.
+#
+#     attr_accessor :spell_dictionary
+#
+#   end
+#
+# == Option Validators
+#
+# OptionParser validators will validate and cast user input values.  In
+# addition to the validators that ship with OptionParser (String, Integer,
+# Float, TrueClass, FalseClass, Array, Regexp, Date, Time, URI, etc.),
+# RDoc::Options adds Path, PathArray and Template.
+
+class RDoc::Options
+
+  ##
+  # The deprecated options.
+
+  DEPRECATED = {
+    '--accessor'      => 'support discontinued',
+    '--diagram'       => 'support discontinued',
+    '--help-output'   => 'support discontinued',
+    '--image-format'  => 'was an option for --diagram',
+    '--inline-source' => 'source code is now always inlined',
+    '--merge'         => 'ri now always merges class information',
+    '--one-file'      => 'support discontinued',
+    '--op-name'       => 'support discontinued',
+    '--opname'        => 'support discontinued',
+    '--promiscuous'   => 'files always only document their content',
+    '--ri-system'     => 'Ruby installers use other techniques',
+  }
+
+  ##
+  # RDoc options ignored (or handled specially) by --write-options
+
+  SPECIAL = %w[
+    coverage_report
+    dry_run
+    encoding
+    files
+    force_output
+    force_update
+    generator
+    generator_name
+    generator_options
+    generators
+    locale
+    op_dir
+    page_dir
+    option_parser
+    pipe
+    rdoc_include
+    root
+    static_path
+    stylesheet_url
+    template
+    template_dir
+    update_output_dir
+    verbosity
+    write_options
+  ]
+
+  ##
+  # Option validator for OptionParser that matches a directory that exists on
+  # the filesystem.
+
+  Directory = Object.new
+
+  ##
+  # Option validator for OptionParser that matches a file or directory that
+  # exists on the filesystem.
+
+  Path = Object.new
+
+  ##
+  # Option validator for OptionParser that matches a comma-separated list of
+  # files or directories that exist on the filesystem.
+
+  PathArray = Object.new
+
+  ##
+  # Option validator for OptionParser that matches a template directory for an
+  # installed generator that lives in
+  # <tt>"rdoc/generator/template/#{template_name}"</tt>
+
+  Template = Object.new
+
+  ##
+  # Character-set for HTML output.  #encoding is preferred over #charset
+
+  attr_accessor :charset
+
+  ##
+  # If true, RDoc will not write any files.
+
+  attr_accessor :dry_run
+
+  ##
+  # The output encoding.  All input files will be transcoded to this encoding.
+  #
+  # The default encoding is UTF-8.  This is set via --encoding.
+
+  attr_accessor :encoding
+
+  ##
+  # Files matching this pattern will be excluded
+
+  attr_writer :exclude
+
+  ##
+  # The list of files to be processed
+
+  attr_accessor :files
+
+  ##
+  # Create the output even if the output directory does not look
+  # like an rdoc output directory
+
+  attr_accessor :force_output
+
+  ##
+  # Scan newer sources than the flag file if true.
+
+  attr_accessor :force_update
+
+  ##
+  # Formatter to mark up text with
+
+  attr_accessor :formatter
+
+  ##
+  # Description of the output generator (set with the <tt>--format</tt> option)
+
+  attr_accessor :generator
+
+  ##
+  # For #==
+
+  attr_reader :generator_name # :nodoc:
+
+  ##
+  # Loaded generator options.  Used to prevent --help from loading the same
+  # options multiple times.
+
+  attr_accessor :generator_options
+
+  ##
+  # Old rdoc behavior: hyperlink all words that match a method name,
+  # even if not preceded by '#' or '::'
+
+  attr_accessor :hyperlink_all
+
+  ##
+  # Include line numbers in the source code
+
+  attr_accessor :line_numbers
+
+  ##
+  # The output locale.
+
+  attr_accessor :locale
+
+  ##
+  # The directory where locale data live.
+
+  attr_accessor :locale_dir
+
+  ##
+  # Name of the file, class or module to display in the initial index page (if
+  # not specified the first file we encounter is used)
+
+  attr_accessor :main_page
+
+  ##
+  # The markup format.
+  # One of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.
+  # See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats].
+  attr_accessor :markup
+
+  ##
+  # If true, only report on undocumented files
+
+  attr_accessor :coverage_report
+
+  ##
+  # The name of the output directory
+
+  attr_accessor :op_dir
+
+  ##
+  # The OptionParser for this instance
+
+  attr_accessor :option_parser
+
+  ##
+  # Output heading decorations?
+  attr_accessor :output_decoration
+
+  ##
+  # Directory where guides, FAQ, and other pages not associated with a class
+  # live.  You may leave this unset if these are at the root of your project.
+
+  attr_accessor :page_dir
+
+  ##
+  # Is RDoc in pipe mode?
+
+  attr_accessor :pipe
+
+  ##
+  # Array of directories to search for files to satisfy an :include:
+
+  attr_accessor :rdoc_include
+
+  ##
+  # Root of the source documentation will be generated for.  Set this when
+  # building documentation outside the source directory.  Defaults to the
+  # current directory.
+
+  attr_accessor :root
+
+  ##
+  # Include the '#' at the front of hyperlinked instance method names
+
+  attr_accessor :show_hash
+
+  ##
+  # Directory to copy static files from
+
+  attr_accessor :static_path
+
+  ##
+  # The number of columns in a tab
+
+  attr_accessor :tab_width
+
+  ##
+  # Template to be used when generating output
+
+  attr_accessor :template
+
+  ##
+  # Directory the template lives in
+
+  attr_accessor :template_dir
+
+  ##
+  # Additional template stylesheets
+
+  attr_accessor :template_stylesheets
+
+  ##
+  # Documentation title
+
+  attr_accessor :title
+
+  ##
+  # Should RDoc update the timestamps in the output dir?
+
+  attr_accessor :update_output_dir
+
+  ##
+  # Verbosity, zero means quiet
+
+  attr_accessor :verbosity
+
+  ##
+  # Warn if rdoc-ref links can't be resolved
+  # Default is +false+
+
+  attr_accessor :warn_missing_rdoc_ref
+
+  ##
+  # URL of web cvs frontend
+
+  attr_accessor :webcvs
+
+  ##
+  # Minimum visibility of a documented method. One of +:public+, +:protected+,
+  # +:private+ or +:nodoc+.
+  #
+  # The +:nodoc+ visibility ignores all directives related to visibility.  The
+  # other visibilities may be overridden on a per-method basis with the :doc:
+  # directive.
+
+  attr_reader :visibility
+
+  ##
+  # Indicates if files of test suites should be skipped
+  attr_accessor :skip_tests
+
+  ##
+  # Embed mixin methods, attributes, and constants into class documentation. Set via
+  # +--[no-]embed-mixins+ (Default is +false+.)
+  attr_accessor :embed_mixins
+
+  ##
+  # Exclude the default patterns as well if true.
+  attr_reader :apply_default_exclude
+
+  ##
+  # Words to be ignored in autolink cross-references
+  attr_accessor :autolink_excluded_words
+
+  def initialize loaded_options = nil # :nodoc:
+    init_ivars
+    override loaded_options if loaded_options
+  end
+
+  DEFAULT_EXCLUDE = %w[
+    ~\z \.orig\z \.rej\z \.bak\z
+    \.gemspec\z
+  ]
+
+  def init_ivars # :nodoc:
+    @autolink_excluded_words = []
+    @dry_run = false
+    @embed_mixins = false
+    @exclude = []
+    @files = nil
+    @force_output = false
+    @force_update = true
+    @generator = nil
+    @generator_name = nil
+    @generator_options = []
+    @generators = RDoc::RDoc::GENERATORS
+    @hyperlink_all = false
+    @line_numbers = false
+    @locale = nil
+    @locale_name = nil
+    @locale_dir = 'locale'
+    @main_page = nil
+    @markup = 'rdoc'
+    @coverage_report = false
+    @op_dir = nil
+    @page_dir = nil
+    @pipe = false
+    @output_decoration = true
+    @rdoc_include = []
+    @root = Pathname(Dir.pwd)
+    @show_hash = false
+    @static_path = []
+    @stylesheet_url = nil # TODO remove in RDoc 4
+    @tab_width = 8
+    @template = nil
+    @template_dir = nil
+    @template_stylesheets = []
+    @title = nil
+    @update_output_dir = true
+    @verbosity = 1
+    @visibility = :protected
+    @warn_missing_rdoc_ref = true
+    @webcvs = nil
+    @write_options = false
+    @encoding = Encoding::UTF_8
+    @charset = @encoding.name
+    @skip_tests = true
+    @apply_default_exclude = true
+  end
+
+  def init_with map # :nodoc:
+    init_ivars
+
+    encoding = map['encoding']
+    @encoding = encoding ? Encoding.find(encoding) : encoding
+
+    @charset        = map['charset']
+    @embed_mixins   = map['embed_mixins']
+    @exclude        = map['exclude']
+    @generator_name = map['generator_name']
+    @hyperlink_all  = map['hyperlink_all']
+    @line_numbers   = map['line_numbers']
+    @locale_name    = map['locale_name']
+    @locale_dir     = map['locale_dir']
+    @main_page      = map['main_page']
+    @markup         = map['markup']
+    @op_dir         = map['op_dir']
+    @show_hash      = map['show_hash']
+    @tab_width      = map['tab_width']
+    @template_dir   = map['template_dir']
+    @title          = map['title']
+    @visibility     = map['visibility']
+    @webcvs         = map['webcvs']
+
+    @apply_default_exclude   = map['apply_default_exclude']
+    @autolink_excluded_words = map['autolink_excluded_words']
+
+    @rdoc_include = sanitize_path map['rdoc_include']
+    @static_path  = sanitize_path map['static_path']
+  end
+
+  def yaml_initialize tag, map # :nodoc:
+    init_with map
+  end
+
+  def override map # :nodoc:
+    if map.has_key?('encoding')
+      encoding = map['encoding']
+      @encoding = encoding ? Encoding.find(encoding) : encoding
+    end
+
+    @charset        = map['charset']        if map.has_key?('charset')
+    @embed_mixins   = map['embed_mixins']   if map.has_key?('embed_mixins')
+    @exclude        = map['exclude']        if map.has_key?('exclude')
+    @generator_name = map['generator_name'] if map.has_key?('generator_name')
+    @hyperlink_all  = map['hyperlink_all']  if map.has_key?('hyperlink_all')
+    @line_numbers   = map['line_numbers']   if map.has_key?('line_numbers')
+    @locale_name    = map['locale_name']    if map.has_key?('locale_name')
+    @locale_dir     = map['locale_dir']     if map.has_key?('locale_dir')
+    @main_page      = map['main_page']      if map.has_key?('main_page')
+    @markup         = map['markup']         if map.has_key?('markup')
+    @op_dir         = map['op_dir']         if map.has_key?('op_dir')
+    @page_dir       = map['page_dir']       if map.has_key?('page_dir')
+    @show_hash      = map['show_hash']      if map.has_key?('show_hash')
+    @tab_width      = map['tab_width']      if map.has_key?('tab_width')
+    @template_dir   = map['template_dir']   if map.has_key?('template_dir')
+    @title          = map['title']          if map.has_key?('title')
+    @visibility     = map['visibility']     if map.has_key?('visibility')
+    @webcvs         = map['webcvs']         if map.has_key?('webcvs')
+    @autolink_excluded_words = map['autolink_excluded_words'] if map.has_key?('autolink_excluded_words')
+    @apply_default_exclude = map['apply_default_exclude'] if map.has_key?('apply_default_exclude')
+
+    @warn_missing_rdoc_ref = map['warn_missing_rdoc_ref'] if map.has_key?('warn_missing_rdoc_ref')
+
+    if map.has_key?('rdoc_include')
+      @rdoc_include = sanitize_path map['rdoc_include']
+    end
+    if map.has_key?('static_path')
+      @static_path  = sanitize_path map['static_path']
+    end
+  end
+
+  def == other # :nodoc:
+    self.class === other and
+      @encoding       == other.encoding       and
+      @embed_mixins   == other.embed_mixins   and
+      @generator_name == other.generator_name and
+      @hyperlink_all  == other.hyperlink_all  and
+      @line_numbers   == other.line_numbers   and
+      @locale         == other.locale         and
+      @locale_dir     == other.locale_dir     and
+      @main_page      == other.main_page      and
+      @markup         == other.markup         and
+      @op_dir         == other.op_dir         and
+      @rdoc_include   == other.rdoc_include   and
+      @show_hash      == other.show_hash      and
+      @static_path    == other.static_path    and
+      @tab_width      == other.tab_width      and
+      @template       == other.template       and
+      @title          == other.title          and
+      @visibility     == other.visibility     and
+      @webcvs         == other.webcvs         and
+      @apply_default_exclude == other.apply_default_exclude and
+      @autolink_excluded_words == other.autolink_excluded_words
+  end
+
+  ##
+  # Check that the files on the command line exist
+
+  def check_files
+    @files.delete_if do |file|
+      if File.exist? file then
+        if File.readable? file then
+          false
+        else
+          warn "file '#{file}' not readable"
+
+          true
+        end
+      else
+        warn "file '#{file}' not found"
+
+        true
+      end
+    end
+  end
+
+  ##
+  # Ensure only one generator is loaded
+
+  def check_generator
+    if @generator then
+      raise OptionParser::InvalidOption,
+        "generator already set to #{@generator_name}"
+    end
+  end
+
+  ##
+  # Set the title, but only if not already set. Used to set the title
+  # from a source file, so that a title set from the command line
+  # will have the priority.
+
+  def default_title=(string)
+    @title ||= string
+  end
+
+  ##
+  # For dumping YAML
+
+  def to_yaml(*options) # :nodoc:
+    encoding = @encoding ? @encoding.name : nil
+
+    yaml = {}
+    yaml['encoding'] = encoding
+    yaml['static_path'] = sanitize_path(@static_path)
+    yaml['rdoc_include'] = sanitize_path(@rdoc_include)
+    yaml['page_dir'] = (sanitize_path([@page_dir]).first if @page_dir)
+
+    ivars = instance_variables.map { |ivar| ivar.to_s[1..-1] }
+    ivars -= SPECIAL
+
+    ivars.sort.each do |ivar|
+      yaml[ivar] = instance_variable_get("@#{ivar}")
+    end
+    yaml.to_yaml
+  end
+
+  ##
+  # Create a regexp for #exclude
+
+  def exclude
+    if @exclude.nil? or Regexp === @exclude then
+      # done, #finish is being re-run
+      @exclude
+    elsif !@apply_default_exclude and @exclude.empty? then
+      nil
+    else
+      exclude = @exclude
+      exclude |= DEFAULT_EXCLUDE if @apply_default_exclude
+      Regexp.new(exclude.join("|"))
+    end
+  end
+
+  ##
+  # Completes any unfinished option setup business such as filtering for
+  # existent files, creating a regexp for #exclude and setting a default
+  # #template.
+
+  def finish
+    if @write_options then
+      write_options
+      exit
+    end
+
+    @op_dir ||= 'doc'
+
+    root = @root.to_s
+    if @rdoc_include.empty? || !@rdoc_include.include?(root)
+      @rdoc_include << root
+    end
+
+    @exclude = self.exclude
+
+    finish_page_dir
+
+    check_files
+
+    # If no template was specified, use the default template for the output
+    # formatter
+
+    unless @template then
+      @template     = @generator_name
+      @template_dir = template_dir_for @template
+    end
+
+    if @locale_name
+      @locale = RDoc::I18n::Locale[@locale_name]
+      @locale.load(@locale_dir)
+    else
+      @locale = nil
+    end
+
+    self
+  end
+
+  ##
+  # Fixes the page_dir to be relative to the root_dir and adds the page_dir to
+  # the files list.
+
+  def finish_page_dir
+    return unless @page_dir
+
+    @files << @page_dir
+
+    page_dir = Pathname(@page_dir)
+    begin
+      page_dir = page_dir.expand_path.relative_path_from @root
+    rescue ArgumentError
+      # On Windows, sometimes crosses different drive letters.
+      page_dir = page_dir.expand_path
+    end
+
+    @page_dir = page_dir
+  end
+
+  ##
+  # Returns a properly-space list of generators and their descriptions.
+
+  def generator_descriptions
+    lengths = []
+
+    generators = RDoc::RDoc::GENERATORS.map do |name, generator|
+      lengths << name.length
+
+      description = generator::DESCRIPTION if
+        generator.const_defined? :DESCRIPTION
+
+      [name, description]
+    end
+
+    longest = lengths.max
+
+    generators.sort.map do |name, description|
+      if description then
+        "  %-*s - %s" % [longest, name, description]
+      else
+        "  #{name}"
+      end
+    end.join "\n"
+  end
+
+  ##
+  # Parses command line options.
+
+  def parse argv
+    ignore_invalid = true
+
+    argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT']
+
+    opts = OptionParser.new do |opt|
+      @option_parser = opt
+      opt.program_name = File.basename $0
+      opt.version = RDoc::VERSION
+      opt.release = nil
+      opt.summary_indent = ' ' * 4
+      opt.banner = <<-EOF
+Usage: #{opt.program_name} [options] [names...]
+
+  Files are parsed, and the information they contain collected, before any
+  output is produced. This allows cross references between all files to be
+  resolved. If a name is a directory, it is traversed. If no names are
+  specified, all Ruby files in the current directory (and subdirectories) are
+  processed.
+
+  How RDoc generates output depends on the output formatter being used, and on
+  the options you give.
+
+  Options can be specified via the RDOCOPT environment variable, which
+  functions similar to the RUBYOPT environment variable for ruby.
+
+    $ export RDOCOPT="--show-hash"
+
+  will make rdoc show hashes in method links by default.  Command-line options
+  always will override those in RDOCOPT.
+
+  Available formatters:
+
+#{generator_descriptions}
+
+  RDoc understands the following file formats:
+
+      EOF
+
+      parsers = Hash.new { |h, parser| h[parser] = [] }
+
+      RDoc::Parser.parsers.each do |regexp, parser|
+        parsers[parser.name.sub('RDoc::Parser::', '')] << regexp.source
+      end
+
+      parsers.sort.each do |parser, regexp|
+        opt.banner += "  - #{parser}: #{regexp.join ', '}\n"
+      end
+      opt.banner += "  - TomDoc:  Only in ruby files\n"
+
+      opt.banner += "\n  The following options are deprecated:\n\n"
+
+      name_length = DEPRECATED.keys.sort_by { |k| k.length }.last.length
+
+      DEPRECATED.sort_by { |k,| k }.each do |name, reason|
+        opt.banner += "    %*1$2$s  %3$s\n" % [-name_length, name, reason]
+      end
+
+      opt.accept Template do |template|
+        template_dir = template_dir_for template
+
+        unless template_dir then
+          $stderr.puts "could not find template #{template}"
+          nil
+        else
+          [template, template_dir]
+        end
+      end
+
+      opt.accept Directory do |directory|
+        directory = File.expand_path directory
+
+        raise OptionParser::InvalidArgument unless File.directory? directory
+
+        directory
+      end
+
+      opt.accept Path do |path|
+        path = File.expand_path path
+
+        raise OptionParser::InvalidArgument unless File.exist? path
+
+        path
+      end
+
+      opt.accept PathArray do |paths,|
+        paths = if paths then
+                  paths.split(',').map { |d| d unless d.empty? }
+                end
+
+        paths.map do |path|
+          path = File.expand_path path
+
+          raise OptionParser::InvalidArgument unless File.exist? path
+
+          path
+        end
+      end
+
+      opt.separator nil
+      opt.separator "Parsing options:"
+      opt.separator nil
+
+      opt.on("--encoding=ENCODING", "-e", Encoding.list.map { |e| e.name },
+             "Specifies the output encoding.  All files",
+             "read will be converted to this encoding.",
+             "The default encoding is UTF-8.",
+             "--encoding is preferred over --charset") do |value|
+               @encoding = Encoding.find value
+               @charset = @encoding.name # may not be valid value
+             end
+
+      opt.separator nil
+
+      opt.on("--locale=NAME",
+             "Specifies the output locale.") do |value|
+        @locale_name = value
+      end
+
+      opt.on("--locale-data-dir=DIR",
+             "Specifies the directory where locale data live.") do |value|
+        @locale_dir = value
+      end
+
+      opt.separator nil
+
+      opt.on("--all", "-a",
+             "Synonym for --visibility=private.") do |value|
+        @visibility = :private
+      end
+
+      opt.separator nil
+
+      opt.on("--exclude=PATTERN", "-x", Regexp,
+             "Do not process files or directories",
+             "matching PATTERN.") do |value|
+        @exclude << value
+      end
+
+      opt.on("--[no-]apply-default-exclude",
+             "Use default PATTERN to exclude.") do |value|
+        @apply_default_exclude = value
+      end
+
+      opt.separator nil
+
+      opt.on("--no-skipping-tests", nil,
+             "Don't skip generating documentation for test and spec files") do |value|
+        @skip_tests = false
+      end
+
+      opt.separator nil
+
+      opt.on("--extension=NEW=OLD", "-E",
+             "Treat files ending with .new as if they",
+             "ended with .old. Using '-E cgi=rb' will",
+             "cause xxx.cgi to be parsed as a Ruby file.") do |value|
+        new, old = value.split(/=/, 2)
+
+        unless new and old then
+          raise OptionParser::InvalidArgument, "Invalid parameter to '-E'"
+        end
+
+        unless RDoc::Parser.alias_extension old, new then
+          raise OptionParser::InvalidArgument, "Unknown extension .#{old} to -E"
+        end
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]force-update", "-U",
+             "Forces rdoc to scan all sources even if",
+             "no files are newer than the flag file.") do |value|
+        @force_update = value
+      end
+
+      opt.separator nil
+
+      opt.on("--pipe", "-p",
+             "Convert RDoc on stdin to HTML") do
+        @pipe = true
+      end
+
+      opt.separator nil
+
+      opt.on("--tab-width=WIDTH", "-w", Integer,
+             "Set the width of tab characters.") do |value|
+        raise OptionParser::InvalidArgument,
+              "#{value} is an invalid tab width" if value <= 0
+        @tab_width = value
+      end
+
+      opt.separator nil
+
+      opt.on("--visibility=VISIBILITY", "-V", RDoc::VISIBILITIES + [:nodoc],
+             "Minimum visibility to document a method.",
+             "One of 'public', 'protected' (the default),",
+             "'private' or 'nodoc' (show everything)") do |value|
+        @visibility = value
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]embed-mixins",
+             "Embed mixin methods, attributes, and constants",
+             "into class documentation. (default false)") do |value|
+        @embed_mixins = value
+      end
+
+      opt.separator nil
+
+      markup_formats = RDoc::Text::MARKUP_FORMAT.keys.sort
+
+      opt.on("--markup=MARKUP", markup_formats,
+             "The markup format for the named files.",
+             "The default is rdoc.  Valid values are:",
+             markup_formats.join(', ')) do |value|
+        @markup = value
+      end
+
+      opt.separator nil
+
+      opt.on("--root=ROOT", Directory,
+             "Root of the source tree documentation",
+             "will be generated for.  Set this when",
+             "building documentation outside the",
+             "source directory.  Default is the",
+             "current directory.") do |root|
+        @root = Pathname(root)
+      end
+
+      opt.separator nil
+
+      opt.on("--page-dir=DIR", Directory,
+             "Directory where guides, your FAQ or",
+             "other pages not associated with a class",
+             "live.  Set this when you don't store",
+             "such files at your project root.",
+             "NOTE: Do not use the same file name in",
+             "the page dir and the root of your project") do |page_dir|
+        @page_dir = page_dir
+      end
+
+      opt.separator nil
+      opt.separator "Common generator options:"
+      opt.separator nil
+
+      opt.on("--force-output", "-O",
+             "Forces rdoc to write the output files,",
+             "even if the output directory exists",
+             "and does not seem to have been created",
+             "by rdoc.") do |value|
+        @force_output = value
+      end
+
+      opt.separator nil
+
+      generator_text = @generators.keys.map { |name| "  #{name}" }.sort
+
+      opt.on("-f", "--fmt=FORMAT", "--format=FORMAT", @generators.keys,
+             "Set the output formatter.  One of:", *generator_text) do |value|
+        check_generator
+
+        @generator_name = value.downcase
+        setup_generator
+      end
+
+      opt.separator nil
+
+      opt.on("--include=DIRECTORIES", "-i", PathArray,
+             "Set (or add to) the list of directories to",
+             "be searched when satisfying :include:",
+             "requests. Can be used more than once.") do |value|
+        @rdoc_include.concat value.map { |dir| dir.strip }
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]coverage-report=[LEVEL]", "--[no-]dcov", "-C", Integer,
+             "Prints a report on undocumented items.",
+             "Does not generate files.") do |value|
+        value = 0 if value.nil? # Integer converts -C to nil
+
+        @coverage_report = value
+        @force_update = true if value
+      end
+
+      opt.separator nil
+
+      opt.on("--output=DIR", "--op", "-o",
+             "Set the output directory.") do |value|
+        @op_dir = value
+      end
+
+      opt.separator nil
+
+      opt.on("-d",
+             "Deprecated --diagram option.",
+             "Prevents firing debug mode",
+             "with legacy invocation.") do |value|
+      end
+
+      opt.separator nil
+      opt.separator 'HTML generator options:'
+      opt.separator nil
+
+      opt.on("--charset=CHARSET", "-c",
+             "Specifies the output HTML character-set.",
+             "Use --encoding instead of --charset if",
+             "available.") do |value|
+        @charset = value
+      end
+
+      opt.separator nil
+
+      opt.on("--autolink-excluded-words=WORDS", Array,
+             "Words to be ignored in autolink cross-references") do |value|
+        @autolink_excluded_words.concat value
+      end
+
+      opt.separator nil
+
+      opt.on("--hyperlink-all", "-A",
+             "Generate hyperlinks for all words that",
+             "correspond to known methods, even if they",
+             "do not start with '#' or '::' (legacy",
+             "behavior).") do |value|
+        @hyperlink_all = value
+      end
+
+      opt.separator nil
+
+      opt.on("--main=NAME", "-m",
+             "NAME will be the initial page displayed.") do |value|
+        @main_page = value
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]line-numbers", "-N",
+             "Include line numbers in the source code.",
+             "By default, only the number of the first",
+             "line is displayed, in a leading comment.") do |value|
+        @line_numbers = value
+      end
+
+      opt.separator nil
+
+      opt.on("--show-hash", "-H",
+             "A name of the form #name in a comment is a",
+             "possible hyperlink to an instance method",
+             "name. When displayed, the '#' is removed",
+             "unless this option is specified.") do |value|
+        @show_hash = value
+      end
+
+      opt.separator nil
+
+      opt.on("--template=NAME", "-T", Template,
+             "Set the template used when generating",
+             "output. The default depends on the",
+             "formatter used.") do |(template, template_dir)|
+        @template     = template
+        @template_dir = template_dir
+      end
+
+      opt.separator nil
+
+      opt.on("--template-stylesheets=FILES", PathArray,
+             "Set (or add to) the list of files to",
+             "include with the html template.") do |value|
+        @template_stylesheets.concat value
+      end
+
+      opt.separator nil
+
+      opt.on("--title=TITLE", "-t",
+             "Set TITLE as the title for HTML output.") do |value|
+        @title = value
+      end
+
+      opt.separator nil
+
+      opt.on("--copy-files=PATH", Path,
+             "Specify a file or directory to copy static",
+             "files from.",
+             "If a file is given it will be copied into",
+             "the output dir.  If a directory is given the",
+             "entire directory will be copied.",
+             "You can use this multiple times") do |value|
+        @static_path << value
+      end
+
+      opt.separator nil
+
+      opt.on("--webcvs=URL", "-W",
+             "Specify a URL for linking to a web frontend",
+             "to CVS. If the URL contains a '\%s', the",
+             "name of the current file will be",
+             "substituted; if the URL doesn't contain a",
+             "'\%s', the filename will be appended to it.") do |value|
+        @webcvs = value
+      end
+
+      opt.separator nil
+      opt.separator "ri generator options:"
+      opt.separator nil
+
+      opt.on("--ri", "-r",
+             "Generate output for use by `ri`. The files",
+             "are stored in the '.rdoc' directory under",
+             "your home directory unless overridden by a",
+             "subsequent --op parameter, so no special",
+             "privileges are needed.") do |value|
+        check_generator
+
+        @generator_name = "ri"
+        @op_dir ||= RDoc::RI::Paths::HOMEDIR
+        setup_generator
+      end
+
+      opt.separator nil
+
+      opt.on("--ri-site", "-R",
+             "Generate output for use by `ri`. The files",
+             "are stored in a site-wide directory,",
+             "making them accessible to others, so",
+             "special privileges are needed.") do |value|
+        check_generator
+
+        @generator_name = "ri"
+        @op_dir = RDoc::RI::Paths.site_dir
+        setup_generator
+      end
+
+      opt.separator nil
+      opt.separator "Generic options:"
+      opt.separator nil
+
+      opt.on("--write-options",
+             "Write .rdoc_options to the current",
+             "directory with the given options.  Not all",
+             "options will be used.  See RDoc::Options",
+             "for details.") do |value|
+        @write_options = true
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]dry-run",
+             "Don't write any files") do |value|
+        @dry_run = value
+      end
+
+      opt.separator nil
+
+      opt.on("-D", "--[no-]debug",
+             "Displays lots on internal stuff.") do |value|
+        $DEBUG_RDOC = value
+      end
+
+      opt.separator nil
+
+      opt.on("--warn-missing-rdoc-ref",
+             "Warn if rdoc-ref links can't be resolved") do |value|
+        @warn_missing_rdoc_ref = value
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]ignore-invalid",
+             "Ignore invalid options and continue",
+             "(default true).") do |value|
+        ignore_invalid = value
+      end
+
+      opt.separator nil
+
+      opt.on("--quiet", "-q",
+             "Don't show progress as we parse.") do |value|
+        @verbosity = 0
+      end
+
+      opt.separator nil
+
+      opt.on("--verbose", "-V",
+             "Display extra progress as RDoc parses") do |value|
+        @verbosity = 2
+      end
+
+      opt.separator nil
+
+      opt.on("--version", "-v", "print the version") do
+        puts opt.version
+        exit
+      end
+
+      opt.separator nil
+
+      opt.on("--help", "-h", "Display this help") do
+        RDoc::RDoc::GENERATORS.each_key do |generator|
+          setup_generator generator
+        end
+
+        puts opt.help
+        exit
+      end
+
+      opt.separator nil
+    end
+
+    setup_generator 'darkfish' if
+      argv.grep(/\A(-f|--fmt|--format|-r|-R|--ri|--ri-site)\b/).empty?
+
+    deprecated = []
+    invalid = []
+
+    begin
+      opts.parse! argv
+    rescue OptionParser::ParseError => e
+      if DEPRECATED[e.args.first] then
+        deprecated << e.args.first
+      elsif %w[--format --ri -r --ri-site -R].include? e.args.first then
+        raise
+      else
+        invalid << e.args.join(' ')
+      end
+
+      retry
+    end
+
+    unless @generator then
+      @generator = RDoc::Generator::Darkfish
+      @generator_name = 'darkfish'
+    end
+
+    if @pipe and not argv.empty? then
+      @pipe = false
+      invalid << '-p (with files)'
+    end
+
+    unless quiet then
+      deprecated.each do |opt|
+        $stderr.puts 'option ' + opt + ' is deprecated: ' + DEPRECATED[opt]
+      end
+    end
+
+    unless invalid.empty? then
+      invalid = "invalid options: #{invalid.join ', '}"
+
+      if ignore_invalid then
+        unless quiet then
+          $stderr.puts invalid
+          $stderr.puts '(invalid options are ignored)'
+        end
+      else
+        unless quiet then
+          $stderr.puts opts
+        end
+        $stderr.puts invalid
+        exit 1
+      end
+    end
+
+    @files = argv.dup
+
+    self
+  end
+
+  ##
+  # Don't display progress as we process the files
+
+  def quiet
+    @verbosity.zero?
+  end
+
+  ##
+  # Set quietness to +bool+
+
+  def quiet= bool
+    @verbosity = bool ? 0 : 1
+  end
+
+  ##
+  # Removes directories from +path+ that are outside the current directory
+
+  def sanitize_path path
+    require 'pathname'
+    dot = Pathname.new('.').expand_path
+
+    path.reject do |item|
+      path = Pathname.new(item).expand_path
+      is_reject = nil
+      relative = nil
+      begin
+        relative = path.relative_path_from(dot).to_s
+      rescue ArgumentError
+        # On Windows, sometimes crosses different drive letters.
+        is_reject = true
+      else
+        is_reject = relative.start_with? '..'
+      end
+      is_reject
+    end
+  end
+
+  ##
+  # Set up an output generator for the named +generator_name+.
+  #
+  # If the found generator responds to :setup_options it will be called with
+  # the options instance.  This allows generators to add custom options or set
+  # default options.
+
+  def setup_generator generator_name = @generator_name
+    @generator = @generators[generator_name]
+
+    unless @generator then
+      raise OptionParser::InvalidArgument,
+            "Invalid output formatter #{generator_name}"
+    end
+
+    return if @generator_options.include? @generator
+
+    @generator_name = generator_name
+    @generator_options << @generator
+
+    if @generator.respond_to? :setup_options then
+      @option_parser ||= OptionParser.new
+      @generator.setup_options self
+    end
+  end
+
+  ##
+  # Finds the template dir for +template+
+
+  def template_dir_for template
+    template_path = File.join 'rdoc', 'generator', 'template', template
+
+    $LOAD_PATH.map do |path|
+      File.join File.expand_path(path), template_path
+    end.find do |dir|
+      File.directory? dir
+    end
+  end
+
+  # Sets the minimum visibility of a documented method.
+  #
+  # Accepts +:public+, +:protected+, +:private+, +:nodoc+, or +:all+.
+  #
+  # When +:all+ is passed, visibility is set to +:private+, similarly to
+  # RDOCOPT="--all", see #visibility for more information.
+
+  def visibility= visibility
+    case visibility
+    when :all
+      @visibility = :private
+    else
+      @visibility = visibility
+    end
+  end
+
+  ##
+  # Displays a warning using Kernel#warn if we're being verbose
+
+  def warn message
+    super message if @verbosity > 1
+  end
+
+  ##
+  # Writes the YAML file .rdoc_options to the current directory containing the
+  # parsed options.
+
+  def write_options
+    RDoc.load_yaml
+
+    File.open '.rdoc_options', 'w' do |io|
+      io.set_encoding Encoding::UTF_8
+
+      io.print to_yaml
+    end
+  end
+
+  ##
+  # Loads options from .rdoc_options if the file exists, otherwise creates a
+  # new RDoc::Options instance.
+
+  def self.load_options
+    options_file = File.expand_path '.rdoc_options'
+    return RDoc::Options.new unless File.exist? options_file
+
+    RDoc.load_yaml
+
+    begin
+      options = YAML.safe_load File.read('.rdoc_options'), permitted_classes: [RDoc::Options, Symbol]
+    rescue Psych::SyntaxError
+      raise RDoc::Error, "#{options_file} is not a valid rdoc options file"
+    end
+
+    return RDoc::Options.new unless options # Allow empty file.
+
+    raise RDoc::Error, "#{options_file} is not a valid rdoc options file" unless
+      RDoc::Options === options or Hash === options
+
+    if Hash === options
+      # Override the default values with the contents of YAML file.
+      options = RDoc::Options.new options
+    end
+
+    options
+  end
+
+end