rdoc 6.3.4.1 → 8.0.0

data/lib/rdoc/options.rb

@@ -74,23 +74,6 @@ require 'pathname'
 
 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
 
@@ -105,13 +88,15 @@ class RDoc::Options
     generator_name
     generator_options
     generators
+    locale
     op_dir
+    page_dir
     option_parser
     pipe
     rdoc_include
     root
+    server_port
     static_path
-    stylesheet_url
     template
     template_dir
     update_output_dir
@@ -231,9 +216,9 @@ class RDoc::Options
   attr_accessor :main_page
 
   ##
-  # The default markup format.  The default is 'rdoc'.  'markdown', 'tomdoc'
-  # and 'rd' are also built-in.
-
+  # The markup format.
+  # One of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.
+  # See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats].
   attr_accessor :markup
 
   ##
@@ -323,6 +308,12 @@ class RDoc::Options
 
   attr_accessor :verbosity
 
+  ##
+  # Warn if rdoc-ref links can't be resolved
+  # Default is +true+
+
+  attr_accessor :warn_missing_rdoc_ref
+
   ##
   # URL of web cvs frontend
 
@@ -338,24 +329,81 @@ class RDoc::Options
 
   attr_reader :visibility
 
-  def initialize loaded_options = nil # :nodoc:
+  ##
+  # When set to a port number, starts a live-reloading server instead of
+  # writing files.  Defaults to +false+ (no server).  Set via
+  # <tt>--server[=PORT]</tt>.
+
+  attr_reader :server_port
+
+  ##
+  # 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
+
+  ##
+  # The prefix to use for class and module page paths
+
+  attr_accessor :class_module_path_prefix
+
+  ##
+  # The prefix to use for file page paths
+
+  attr_accessor :file_path_prefix
+
+  ##
+  # The preferred root URL for the documentation
+
+  attr_accessor :canonical_root
+
+  ##
+  # Custom footer content configuration for themes that support it.
+  # Currently only supported by the Aliki theme.
+  #
+  # A hash where keys are column titles and values are hashes of link text => URL pairs.
+  # Each column will be displayed in the upper footer section.
+  #
+  # Example:
+  #   {
+  #     "DOCUMENTATION" => {"Home" => "/index.html", "Guide" => "/guide.html"},
+  #     "RESOURCES" => {"RDoc" => "https://ruby.github.io/rdoc/", "GitHub" => "https://github.com/ruby/rdoc"}
+  #   }
+
+  attr_accessor :footer_content
+
+  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
-    @exclude = %w[
-      ~\z \.orig\z \.rej\z \.bak\z
-      \.gemspec\z
-    ]
+    @embed_mixins = false
+    @exclude = []
     @files = nil
     @force_output = false
     @force_update = true
-    @generator = nil
-    @generator_name = nil
-    @generator_options = []
+    @generator_name = "aliki"
     @generators = RDoc::RDoc::GENERATORS
+    @generator_options = []
     @hyperlink_all = false
     @line_numbers = false
     @locale = nil
@@ -370,9 +418,9 @@ class RDoc::Options
     @output_decoration = true
     @rdoc_include = []
     @root = Pathname(Dir.pwd)
+    @server_port = false
     @show_hash = false
     @static_path = []
-    @stylesheet_url = nil # TODO remove in RDoc 4
     @tab_width = 8
     @template = nil
     @template_dir = nil
@@ -381,19 +429,27 @@ class RDoc::Options
     @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
+    @class_module_path_prefix = nil
+    @file_path_prefix = nil
+    @canonical_root = nil
+    @footer_content = nil
   end
 
-  def init_with map # :nodoc:
+  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']
@@ -410,21 +466,26 @@ class RDoc::Options
     @visibility     = map['visibility']
     @webcvs         = map['webcvs']
 
+    @apply_default_exclude   = map['apply_default_exclude']
+    @autolink_excluded_words = map['autolink_excluded_words']
+    @footer_content          = map['footer_content']
+
     @rdoc_include = sanitize_path map['rdoc_include']
     @static_path  = sanitize_path map['static_path']
   end
 
-  def yaml_initialize tag, map # :nodoc:
+  def yaml_initialize(tag, map) # :nodoc:
     init_with map
   end
 
-  def override map # :nodoc:
+  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')
@@ -434,12 +495,19 @@ class RDoc::Options
     @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')
+    @canonical_root = map['canonical_root'] if map.has_key?('canonical_root')
+    @footer_content = map['footer_content'] if map.has_key?('footer_content')
+
+    @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']
@@ -449,14 +517,15 @@ class RDoc::Options
     end
   end
 
-  def == other # :nodoc:
+  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
+      @locale_dir     == other.locale_dir     and
       @main_page      == other.main_page      and
       @markup         == other.markup         and
       @op_dir         == other.op_dir         and
@@ -467,7 +536,9 @@ class RDoc::Options
       @template       == other.template       and
       @title          == other.title          and
       @visibility     == other.visibility     and
-      @webcvs         == other.webcvs
+      @webcvs         == other.webcvs         and
+      @apply_default_exclude == other.apply_default_exclude and
+      @autolink_excluded_words == other.autolink_excluded_words
   end
 
   ##
@@ -513,18 +584,26 @@ class RDoc::Options
   ##
   # For dumping YAML
 
-  def encode_with coder # :nodoc:
+  def to_yaml(*options) # :nodoc:
     encoding = @encoding ? @encoding.name : nil
 
-    coder.add 'encoding', encoding
-    coder.add 'static_path',  sanitize_path(@static_path)
-    coder.add 'rdoc_include', sanitize_path(@rdoc_include)
+    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|
-      coder.add ivar, instance_variable_get("@#{ivar}")
+      yaml[ivar] = instance_variable_get("@#{ivar}")
+    end
+
+    if yaml.respond_to?(:to_yaml)
+      yaml.to_yaml
+    else
+      RDoc.yaml_serializer.dump(yaml)
     end
   end
 
@@ -535,10 +614,12 @@ class RDoc::Options
     if @exclude.nil? or Regexp === @exclude then
       # done, #finish is being re-run
       @exclude
-    elsif @exclude.empty? then
+    elsif !@apply_default_exclude and @exclude.empty? then
       nil
     else
-      Regexp.new(@exclude.join("|"))
+      exclude = @exclude
+      exclude |= DEFAULT_EXCLUDE if @apply_default_exclude
+      Regexp.new(exclude.join("|"))
     end
   end
 
@@ -548,11 +629,17 @@ class RDoc::Options
   # #template.
 
   def finish
+    if @write_options then
+      write_options
+      exit
+    end
+
     @op_dir ||= 'doc'
 
-    @rdoc_include << "." if @rdoc_include.empty?
     root = @root.to_s
-    @rdoc_include << root unless @rdoc_include.include?(root)
+    if @rdoc_include.empty? || !@rdoc_include.include?(root)
+      @rdoc_include << root
+    end
 
     @exclude = self.exclude
 
@@ -585,14 +672,14 @@ class RDoc::Options
   def finish_page_dir
     return unless @page_dir
 
-    @files << @page_dir.to_s
+    @files << @page_dir
 
-    page_dir = nil
+    page_dir = Pathname(@page_dir)
     begin
-      page_dir = @page_dir.expand_path.relative_path_from @root
+      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
+      page_dir = page_dir.expand_path
     end
 
     @page_dir = page_dir
@@ -627,7 +714,7 @@ class RDoc::Options
   ##
   # Parses command line options.
 
-  def parse argv
+  def parse(argv)
     ignore_invalid = true
 
     argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT']
@@ -666,7 +753,7 @@ Usage: #{opt.program_name} [options] [names...]
 
       EOF
 
-      parsers = Hash.new { |h,parser| h[parser] = [] }
+      parsers = Hash.new { |h, parser| h[parser] = [] }
 
       RDoc::Parser.parsers.each do |regexp, parser|
         parsers[parser.name.sub('RDoc::Parser::', '')] << regexp.source
@@ -677,14 +764,6 @@ Usage: #{opt.program_name} [options] [names...]
       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
 
@@ -766,6 +845,18 @@ Usage: #{opt.program_name} [options] [names...]
         @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",
@@ -809,7 +900,7 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      opt.on("--visibility=VISIBILITY", "-V", RDoc::VISIBILITIES + [:nodoc],
+      opt.on("--visibility=VISIBILITY", RDoc::VISIBILITIES + [:nodoc],
              "Minimum visibility to document a method.",
              "One of 'public', 'protected' (the default),",
              "'private' or 'nodoc' (show everything)") do |value|
@@ -818,6 +909,14 @@ Usage: #{opt.program_name} [options] [names...]
 
       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,
@@ -847,7 +946,7 @@ Usage: #{opt.program_name} [options] [names...]
              "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 = Pathname(page_dir)
+        @page_dir = page_dir
       end
 
       opt.separator nil
@@ -901,14 +1000,6 @@ Usage: #{opt.program_name} [options] [names...]
         @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
@@ -922,6 +1013,13 @@ Usage: #{opt.program_name} [options] [names...]
 
       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",
@@ -971,7 +1069,7 @@ Usage: #{opt.program_name} [options] [names...]
       opt.on("--template-stylesheets=FILES", PathArray,
              "Set (or add to) the list of files to",
              "include with the html template.") do |value|
-        @template_stylesheets << value
+        @template_stylesheets.concat value
       end
 
       opt.separator nil
@@ -1039,6 +1137,15 @@ Usage: #{opt.program_name} [options] [names...]
       opt.separator "Generic options:"
       opt.separator nil
 
+      opt.on("--server[=PORT]", Integer,
+             "Start a web server to preview",
+             "documentation with live reload.",
+             "Defaults to port 4000.") do |port|
+        @server_port = port || 4000
+      end
+
+      opt.separator nil
+
       opt.on("--write-options",
              "Write .rdoc_options to the current",
              "directory with the given options.  Not all",
@@ -1063,6 +1170,13 @@ Usage: #{opt.program_name} [options] [names...]
 
       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|
@@ -1104,18 +1218,12 @@ Usage: #{opt.program_name} [options] [names...]
       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
+      if %w[--format --ri -r --ri-site -R].include? e.args.first then
         raise
       else
         invalid << e.args.join(' ')
@@ -1124,22 +1232,13 @@ Usage: #{opt.program_name} [options] [names...]
       retry
     end
 
-    unless @generator then
-      @generator = RDoc::Generator::Darkfish
-      @generator_name = 'darkfish'
-    end
+    setup_generator unless @generator
 
     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 ', '}"
 
@@ -1159,13 +1258,6 @@ Usage: #{opt.program_name} [options] [names...]
 
     @files = argv.dup
 
-    finish
-
-    if @write_options then
-      write_options
-      exit
-    end
-
     self
   end
 
@@ -1179,14 +1271,14 @@ Usage: #{opt.program_name} [options] [names...]
   ##
   # Set quietness to +bool+
 
-  def quiet= bool
+  def quiet=(bool)
     @verbosity = bool ? 0 : 1
   end
 
   ##
   # Removes directories from +path+ that are outside the current directory
 
-  def sanitize_path path
+  def sanitize_path(path)
     require 'pathname'
     dot = Pathname.new('.').expand_path
 
@@ -1213,7 +1305,7 @@ Usage: #{opt.program_name} [options] [names...]
   # the options instance.  This allows generators to add custom options or set
   # default options.
 
-  def setup_generator generator_name = @generator_name
+  def setup_generator(generator_name = @generator_name)
     @generator = @generators[generator_name]
 
     unless @generator then
@@ -1235,7 +1327,7 @@ Usage: #{opt.program_name} [options] [names...]
   ##
   # Finds the template dir for +template+
 
-  def template_dir_for template
+  def template_dir_for(template)
     template_path = File.join 'rdoc', 'generator', 'template', template
 
     $LOAD_PATH.map do |path|
@@ -1252,7 +1344,7 @@ Usage: #{opt.program_name} [options] [names...]
   # When +:all+ is passed, visibility is set to +:private+, similarly to
   # RDOCOPT="--all", see #visibility for more information.
 
-  def visibility= visibility
+  def visibility=(visibility)
     case visibility
     when :all
       @visibility = :private
@@ -1264,7 +1356,7 @@ Usage: #{opt.program_name} [options] [names...]
   ##
   # Displays a warning using Kernel#warn if we're being verbose
 
-  def warn message
+  def warn(message)
     super message if @verbosity > 1
   end
 
@@ -1278,8 +1370,43 @@ Usage: #{opt.program_name} [options] [names...]
     File.open '.rdoc_options', 'w' do |io|
       io.set_encoding Encoding::UTF_8
 
-      YAML.dump self, io
+      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
+
+    content = File.read('.rdoc_options')
+
+    if defined?(Psych)
+      begin
+        options = Psych.safe_load content, permitted_classes: [RDoc::Options, Symbol]
+      rescue Psych::SyntaxError
+        raise RDoc::Error, "#{options_file} is not a valid rdoc options file"
+      end
+    else
+      options = RDoc.yaml_serializer.load(content)
+    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