rdoc 5.1.0 → 6.13.1

data/lib/rdoc/encoding.rb

@@ -1,5 +1,5 @@
 # coding: US-ASCII
-# frozen_string_literal: false
+# frozen_string_literal: true
 
 ##
 # This class is a wrapper around File IO and Encoding that helps RDoc load
@@ -7,6 +7,18 @@
 
 module RDoc::Encoding
 
+  HEADER_REGEXP = /^
+    (?:
+      \A\#!.*\n
+      |
+      ^\#\s+frozen[-_]string[-_]literal[=:].+\n
+      |
+      ^\#[^\n]+\b(?:en)?coding[=:]\s*(?<name>[^\s;]+).*\n
+      |
+      <\?xml[^?]*encoding=(?<quote>["'])(?<name>.*?)\k<quote>.*\n
+    )+
+  /xi # :nodoc:
+
   ##
   # Reads the contents of +filename+ and handles any encoding directives in
   # the file.
@@ -18,31 +30,32 @@ module RDoc::Encoding
   # unknown character in the target encoding will be replaced with '?'
 
   def self.read_file filename, encoding, force_transcode = false
-    content = open filename, "rb" do |f| f.read end
+    content = File.open filename, "rb" do |f| f.read end
     content.gsub!("\r\n", "\n") if RUBY_PLATFORM =~ /mswin|mingw/
 
     utf8 = content.sub!(/\A\xef\xbb\xbf/, '')
 
-    RDoc::Encoding.set_encoding content
+    enc = RDoc::Encoding.detect_encoding content
+    content = RDoc::Encoding.change_encoding content, enc if enc
 
     begin
       encoding ||= Encoding.default_external
       orig_encoding = content.encoding
 
       if not orig_encoding.ascii_compatible? then
-        content.encode! encoding
+        content = content.encode encoding
       elsif utf8 then
-        content.force_encoding Encoding::UTF_8
-        content.encode! encoding
+        content = RDoc::Encoding.change_encoding content, Encoding::UTF_8
+        content = content.encode encoding
       else
         # assume the content is in our output encoding
-        content.force_encoding encoding
+        content = RDoc::Encoding.change_encoding content, encoding
       end
 
       unless content.valid_encoding? then
         # revert and try to transcode
-        content.force_encoding orig_encoding
-        content.encode! encoding
+        content = RDoc::Encoding.change_encoding content, orig_encoding
+        content = content.encode encoding
       end
 
       unless content.valid_encoding? then
@@ -52,10 +65,11 @@ module RDoc::Encoding
     rescue Encoding::InvalidByteSequenceError,
            Encoding::UndefinedConversionError => e
       if force_transcode then
-        content.force_encoding orig_encoding
-        content.encode!(encoding,
-                        :invalid => :replace, :undef => :replace,
-                        :replace => '?')
+        content = RDoc::Encoding.change_encoding content, orig_encoding
+        content = content.encode(encoding,
+                                 :invalid => :replace,
+                                 :undef => :replace,
+                                 :replace => '?')
         return content
       else
         warn "unable to convert #{e.message} for #{filename}, skipping"
@@ -72,37 +86,35 @@ module RDoc::Encoding
     nil
   end
 
-  def self.remove_frozen_string_literal string
-    string =~ /\A(?:#!.*\n)?(.*\n)/
-    first_line = $1
-
-    if first_line =~ /\A# +frozen[-_]string[-_]literal[=:].+$/i
-      string.sub! first_line, ''
-    end
-  end
-
   ##
-  # Sets the encoding of +string+ based on the magic comment
-
-  def self.set_encoding string
-    remove_frozen_string_literal string
-
-    string =~ /\A(?:#!.*\n)?(.*\n)/
+  # Detects the encoding of +string+ based on the magic comment
 
-    first_line = $1
+  def self.detect_encoding string
+    result = HEADER_REGEXP.match string
+    name = result && result[:name]
 
-    name = case first_line
-           when /^<\?xml[^?]*encoding=(["'])(.*?)\1/ then $2
-           when /\b(?:en)?coding[=:]\s*([^\s;]+)/i   then $1
-           else                                           return
-           end
+    name ? Encoding.find(name) : nil
+  end
 
-    string.sub! first_line, ''
+  ##
+  # Removes magic comments and shebang
 
-    remove_frozen_string_literal string
+  def self.remove_magic_comment string
+    string.sub HEADER_REGEXP do |s|
+      s.gsub(/[^\n]/, '')
+    end
+  end
 
-    enc = Encoding.find name
-    string.force_encoding enc if enc
+  ##
+  # Changes encoding based on +encoding+ without converting and returns new
+  # string
+
+  def self.change_encoding text, encoding
+    if text.kind_of? RDoc::Comment
+      text.encode! encoding
+    else
+      String.new text, encoding: encoding
+    end
   end
 
 end

data/lib/rdoc/erb_partial.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 ##
 # Allows an ERB template to be rendered in the context (binding) of an
 # existing ERB template evaluation.
@@ -12,8 +12,7 @@ class RDoc::ERBPartial < ERB
   def set_eoutvar compiler, eoutvar = '_erbout'
     super
 
-    compiler.pre_cmd = ["#{eoutvar} ||= ''"]
+    compiler.pre_cmd = ["#{eoutvar} ||= +''"]
   end
 
 end
-

data/lib/rdoc/erbio.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 require 'erb'
 
 ##
@@ -9,7 +9,7 @@ require 'erb'
 #
 #   erbio = RDoc::ERBIO.new '<%= "hello world" %>', nil, nil
 #
-#   open 'hello.txt', 'w' do |io|
+#   File.open 'hello.txt', 'w' do |io|
 #     erbio.result binding
 #   end
 #
@@ -20,8 +20,8 @@ class RDoc::ERBIO < ERB
   ##
   # Defaults +eoutvar+ to 'io', otherwise is identical to ERB's initialize
 
-  def initialize str, safe_level = nil, trim_mode = nil, eoutvar = 'io'
-    super
+  def initialize str, trim_mode: nil, eoutvar: 'io'
+    super(str, trim_mode: trim_mode, eoutvar: eoutvar)
   end
 
   ##
@@ -35,4 +35,3 @@ class RDoc::ERBIO < ERB
   end
 
 end
-

data/lib/rdoc/generator/darkfish.rb

@@ -1,10 +1,10 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 # -*- mode: ruby; ruby-indent-level: 2; tab-width: 2 -*-
 
 require 'erb'
 require 'fileutils'
 require 'pathname'
-require 'rdoc/generator/markup'
+require_relative 'markup'
 
 ##
 # Darkfish RDoc HTML Generator
@@ -73,12 +73,6 @@ class RDoc::Generator::Darkfish
       css/rdoc.css
   ]
 
-  ##
-  # Path to this file's parent directory. Used to find templates and other
-  # resources.
-
-  GENERATOR_DIR = File.join 'rdoc', 'generator'
-
   ##
   # Release Version
 
@@ -184,22 +178,6 @@ class RDoc::Generator::Darkfish
     $stderr.puts(*msg)
   end
 
-  ##
-  # Directory where generated class HTML files live relative to the output
-  # dir.
-
-  def class_dir
-    nil
-  end
-
-  ##
-  # Directory where generated class HTML files live relative to the output
-  # dir.
-
-  def file_dir
-    nil
-  end
-
   ##
   # Create the directories the generated docs will live in if they don't
   # already exist.
@@ -220,8 +198,8 @@ class RDoc::Generator::Darkfish
       install_rdoc_static_file @template_dir + item, "./#{item}", options
     end
 
-    @options.template_stylesheets.each do |stylesheet|
-      FileUtils.cp stylesheet, '.', options
+    unless @options.template_stylesheets.empty?
+      FileUtils.cp @options.template_stylesheets, '.', **options
     end
 
     Dir[(@template_dir + "{js,images}/**/*").to_s].each do |path|
@@ -269,7 +247,7 @@ class RDoc::Generator::Darkfish
 
     @options.static_path.each do |path|
       unless File.directory? path then
-        FileUtils.install path, @outputdir, fu_options.merge(:mode => 0644)
+        FileUtils.install path, @outputdir, **fu_options.merge(:mode => 0644)
         next
       end
 
@@ -278,9 +256,9 @@ class RDoc::Generator::Darkfish
           dest_file = @outputdir + entry
 
           if File.directory? entry then
-            FileUtils.mkdir_p entry, fu_options
+            FileUtils.mkdir_p entry, **fu_options
           else
-            FileUtils.install entry, dest_file, fu_options.merge(:mode => 0644)
+            FileUtils.install entry, dest_file, **fu_options.merge(:mode => 0644)
           end
         end
       end
@@ -301,8 +279,6 @@ class RDoc::Generator::Darkfish
   # Generate an index page which lists all the classes which are documented.
 
   def generate_index
-    setup
-
     template_file = @template_dir + 'index.rhtml'
     return unless template_file.exist?
 
@@ -313,12 +289,19 @@ class RDoc::Generator::Darkfish
     search_index_rel_prefix = rel_prefix
     search_index_rel_prefix += @asset_rel_path if @file_output
 
-    # suppress 1.9.3 warning
-    asset_rel_prefix = asset_rel_prefix = rel_prefix + @asset_rel_path
+    asset_rel_prefix = rel_prefix + @asset_rel_path
 
     @title = @options.title
+    @main_page = @files.find { |f| f.full_name == @options.main_page }
 
-    render_template template_file, out_file do |io| binding end
+    render_template template_file, out_file do |io|
+      here = binding
+      # suppress 1.9.3 warning
+      here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
+      # some partials rely on the presence of current variable to render
+      here.local_variable_set(:current, @main_page) if @main_page
+      here
+    end
   rescue => e
     error = RDoc::Error.new \
       "error generating index.html: #{e.message} (#{e.class})"
@@ -331,8 +314,6 @@ class RDoc::Generator::Darkfish
   # Generates a class file for +klass+
 
   def generate_class klass, template_file = nil
-    setup
-
     current = klass
 
     template_file ||= @template_dir + 'class.rhtml'
@@ -343,22 +324,26 @@ class RDoc::Generator::Darkfish
     search_index_rel_prefix = rel_prefix
     search_index_rel_prefix += @asset_rel_path if @file_output
 
-    # suppress 1.9.3 warning
-    asset_rel_prefix = asset_rel_prefix = rel_prefix + @asset_rel_path
-    svninfo          = svninfo          = get_svninfo(current)
+    asset_rel_prefix = rel_prefix + @asset_rel_path
+
+    breadcrumb = # used in templates
+    breadcrumb = generate_nesting_namespaces_breadcrumb(current, rel_prefix)
 
     @title = "#{klass.type} #{klass.full_name} - #{@options.title}"
 
     debug_msg "  rendering #{out_file}"
-    render_template template_file, out_file do |io| binding end
+    render_template template_file, out_file do |io|
+      here = binding
+      # suppress 1.9.3 warning
+      here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
+      here
+    end
   end
 
   ##
   # Generate a documentation file for each class and module
 
   def generate_class_files
-    setup
-
     template_file = @template_dir + 'class.rhtml'
     template_file = @template_dir + 'classpage.rhtml' unless
       template_file.exist?
@@ -384,8 +369,6 @@ class RDoc::Generator::Darkfish
   # Generate a documentation file for each file
 
   def generate_file_files
-    setup
-
     page_file     = @template_dir + 'page.rhtml'
     fileinfo_file = @template_dir + 'fileinfo.rhtml'
 
@@ -416,8 +399,7 @@ class RDoc::Generator::Darkfish
       search_index_rel_prefix = rel_prefix
       search_index_rel_prefix += @asset_rel_path if @file_output
 
-      # suppress 1.9.3 warning
-      asset_rel_prefix = asset_rel_prefix = rel_prefix + @asset_rel_path
+      asset_rel_prefix = rel_prefix + @asset_rel_path
 
       unless filepage_file then
         if file.text? then
@@ -434,7 +416,13 @@ class RDoc::Generator::Darkfish
       @title += " - #{@options.title}"
       template_file ||= filepage_file
 
-      render_template template_file, out_file do |io| binding end
+      render_template template_file, out_file do |io|
+        here = binding
+        # suppress 1.9.3 warning
+        here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
+        here.local_variable_set(:current, current)
+        here
+      end
     end
   rescue => e
     error =
@@ -448,8 +436,6 @@ class RDoc::Generator::Darkfish
   # Generate a page file for +file+
 
   def generate_page file
-    setup
-
     template_file = @template_dir + 'page.rhtml'
 
     out_file = @outputdir + file.path
@@ -458,22 +444,25 @@ class RDoc::Generator::Darkfish
     search_index_rel_prefix = rel_prefix
     search_index_rel_prefix += @asset_rel_path if @file_output
 
-    # suppress 1.9.3 warning
-    current          = current          = file
-    asset_rel_prefix = asset_rel_prefix = rel_prefix + @asset_rel_path
+    current          = file
+    asset_rel_prefix = rel_prefix + @asset_rel_path
 
     @title = "#{file.page_name} - #{@options.title}"
 
     debug_msg "  rendering #{out_file}"
-    render_template template_file, out_file do |io| binding end
+    render_template template_file, out_file do |io|
+      here = binding
+      # suppress 1.9.3 warning
+      here.local_variable_set(:current, current)
+      here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
+      here
+    end
   end
 
   ##
   # Generates the 404 page for the RDoc servlet
 
   def generate_servlet_not_found message
-    setup
-
     template_file = @template_dir + 'servlet_not_found.rhtml'
     return unless template_file.exist?
 
@@ -483,12 +472,16 @@ class RDoc::Generator::Darkfish
     search_index_rel_prefix = rel_prefix
     search_index_rel_prefix += @asset_rel_path if @file_output
 
-    # suppress 1.9.3 warning
-    asset_rel_prefix = asset_rel_prefix = ''
+    asset_rel_prefix = ''
 
     @title = 'Not Found'
 
-    render_template template_file do |io| binding end
+    render_template template_file do |io|
+      here = binding
+      # suppress 1.9.3 warning
+      here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
+      here
+    end
   rescue => e
     error = RDoc::Error.new \
       "error generating servlet_not_found: #{e.message} (#{e.class})"
@@ -501,8 +494,6 @@ class RDoc::Generator::Darkfish
   # Generates the servlet root page for the RDoc servlet
 
   def generate_servlet_root installed
-    setup
-
     template_file = @template_dir + 'servlet_root.rhtml'
     return unless template_file.exist?
 
@@ -528,8 +519,6 @@ class RDoc::Generator::Darkfish
   # Generate an index page which lists all the classes which are documented.
 
   def generate_table_of_contents
-    setup
-
     template_file = @template_dir + 'table_of_contents.rhtml'
     return unless template_file.exist?
 
@@ -540,12 +529,16 @@ class RDoc::Generator::Darkfish
     search_index_rel_prefix = rel_prefix
     search_index_rel_prefix += @asset_rel_path if @file_output
 
-    # suppress 1.9.3 warning
-    asset_rel_prefix = asset_rel_prefix = rel_prefix + @asset_rel_path
+    asset_rel_prefix = rel_prefix + @asset_rel_path
 
     @title = "Table of Contents - #{@options.title}"
 
-    render_template template_file, out_file do |io| binding end
+    render_template template_file, out_file do |io|
+      here = binding
+      # suppress 1.9.3 warning
+      here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
+      here
+    end
   rescue => e
     error = RDoc::Error.new \
       "error generating table_of_contents.html: #{e.message} (#{e.class})"
@@ -558,16 +551,16 @@ class RDoc::Generator::Darkfish
     return unless source.exist?
 
     begin
-      FileUtils.mkdir_p File.dirname(destination), options
+      FileUtils.mkdir_p File.dirname(destination), **options
 
       begin
-        FileUtils.ln source, destination, options
+        FileUtils.ln source, destination, **options
       rescue Errno::EEXIST
         FileUtils.rm destination
         retry
       end
     rescue
-      FileUtils.cp source, destination, options
+      FileUtils.cp source, destination, **options
     end
   end
 
@@ -583,62 +576,10 @@ class RDoc::Generator::Darkfish
 
     @classes = @store.all_classes_and_modules.sort
     @files   = @store.all_files.sort
-    @methods = @classes.map { |m| m.method_list }.flatten.sort
+    @methods = @classes.flat_map { |m| m.method_list }.sort
     @modsort = get_sorted_module_list @classes
   end
 
-  ##
-  # Return a string describing the amount of time in the given number of
-  # seconds in terms a human can understand easily.
-
-  def time_delta_string seconds
-    return 'less than a minute'          if seconds < 60
-    return "#{seconds / 60} minute#{seconds / 60 == 1 ? '' : 's'}" if
-                                            seconds < 3000     # 50 minutes
-    return 'about one hour'              if seconds < 5400     # 90 minutes
-    return "#{seconds / 3600} hours"     if seconds < 64800    # 18 hours
-    return 'one day'                     if seconds < 86400    #  1 day
-    return 'about one day'               if seconds < 172800   #  2 days
-    return "#{seconds / 86400} days"     if seconds < 604800   #  1 week
-    return 'about one week'              if seconds < 1209600  #  2 week
-    return "#{seconds / 604800} weeks"   if seconds < 7257600  #  3 months
-    return "#{seconds / 2419200} months" if seconds < 31536000 #  1 year
-    return "#{seconds / 31536000} years"
-  end
-
-  # %q$Id: darkfish.rb 52 2009-01-07 02:08:11Z deveiant $"
-  SVNID_PATTERN = /
-    \$Id:\s
-    (\S+)\s                # filename
-    (\d+)\s                # rev
-    (\d{4}-\d{2}-\d{2})\s  # Date (YYYY-MM-DD)
-    (\d{2}:\d{2}:\d{2}Z)\s # Time (HH:MM:SSZ)
-    (\w+)\s                # committer
-    \$$
-  /x
-
-  ##
-  # Try to extract Subversion information out of the first constant whose
-  # value looks like a subversion Id tag. If no matching constant is found,
-  # and empty hash is returned.
-
-  def get_svninfo klass
-    constants = klass.constants or return {}
-
-    constants.find { |c| c.value =~ SVNID_PATTERN } or return {}
-
-    filename, rev, date, time, committer = $~.captures
-    commitdate = Time.parse "#{date} #{time}"
-
-    return {
-      :filename    => filename,
-      :rev         => Integer(rev),
-      :commitdate  => commitdate,
-      :commitdelta => time_delta_string(Time.now - commitdate),
-      :committer   => committer,
-    }
-  end
-
   ##
   # Creates a template from its components and the +body_file+.
   #
@@ -650,7 +591,6 @@ class RDoc::Generator::Darkfish
     return body if body =~ /<html/
 
     head_file = @template_dir + '_head.rhtml'
-    footer_file = @template_dir + '_footer.rhtml'
 
     <<-TEMPLATE
 <!DOCTYPE html>
@@ -660,8 +600,6 @@ class RDoc::Generator::Darkfish
 #{head_file.read}
 
 #{body}
-
-#{footer_file.read}
     TEMPLATE
   end
 
@@ -751,9 +689,124 @@ class RDoc::Generator::Darkfish
       erbout = "_erbout_#{file_var}"
     end
 
-    template = klass.new template, nil, '<>', erbout
+    template = klass.new template, trim_mode: '-', eoutvar: erbout
     @template_cache[file] = template
     template
   end
 
+  # :stopdoc:
+  ParagraphExcerptRegexpOther = %r[\b\w[^./:]++\.]
+  # use \p/\P{letter} instead of \w/\W in Unicode
+  ParagraphExcerptRegexpUnicode = %r[\b\p{letter}[^./:]++\.]
+  # :startdoc:
+
+  # Returns an excerpt of the comment for usage in meta description tags
+  def excerpt(comment)
+    text = case comment
+    when RDoc::Comment
+      comment.text
+    else
+      comment
+    end
+
+    # Match from a capital letter to the first period, discarding any links, so
+    # that we don't end up matching badges in the README
+    pattern = ParagraphExcerptRegexpUnicode
+    begin
+      first_paragraph_match = text.match(pattern)
+    rescue Encoding::CompatibilityError
+      # The doc is non-ASCII text and encoded in other than Unicode base encodings.
+      raise if pattern == ParagraphExcerptRegexpOther
+      pattern = ParagraphExcerptRegexpOther
+      retry
+    end
+    return text[0...150].tr_s("\n", " ").squeeze(" ") unless first_paragraph_match
+
+    extracted_text = first_paragraph_match[0]
+    second_paragraph = text.match(pattern, first_paragraph_match.end(0))
+    extracted_text << " " << second_paragraph[0] if second_paragraph
+
+    extracted_text[0...150].tr_s("\n", " ").squeeze(" ")
+  end
+
+  def generate_ancestor_list(ancestors, klass)
+    return '' if ancestors.empty?
+
+    ancestor = ancestors.shift
+    content = +'<ul><li>'
+
+    if ancestor.is_a?(RDoc::NormalClass)
+      content << "<a href=\"#{klass.aref_to ancestor.path}\">#{ancestor.full_name}</a>"
+    else
+      content << ancestor.to_s
+    end
+
+    # Recursively call the method for the remaining ancestors
+    content << generate_ancestor_list(ancestors, klass)
+
+    content << '</li></ul>'
+  end
+
+  def generate_class_link(klass, rel_prefix)
+    if klass.display?
+      %(<code><a href="#{rel_prefix}/#{klass.path}">#{klass.name}</a></code>)
+    else
+      %(<code>#{klass.name}</code>)
+    end
+  end
+
+  def generate_class_index_content(classes, rel_prefix)
+    grouped_classes = group_classes_by_namespace_for_sidebar(classes)
+    return '' unless top = grouped_classes[nil]
+
+    solo = top.one? { |klass| klass.display? }
+    traverse_classes(top, grouped_classes, rel_prefix, solo)
+  end
+
+  def traverse_classes(klasses, grouped_classes, rel_prefix, solo = false)
+    content = +'<ul class="link-list">'
+
+    klasses.each do |index_klass|
+      if children = grouped_classes[index_klass.full_name]
+        content << %(<li><details#{solo ? ' open' : ''}><summary>#{generate_class_link(index_klass, rel_prefix)}</summary>)
+        content << traverse_classes(children, grouped_classes, rel_prefix)
+        content << '</details></li>'
+        solo = false
+      elsif index_klass.display?
+        content << %(<li>#{generate_class_link(index_klass, rel_prefix)}</li>)
+      end
+    end
+
+    "#{content}</ul>"
+  end
+
+  def group_classes_by_namespace_for_sidebar(classes)
+    grouped_classes = classes.group_by do |klass|
+      klass.full_name[/\A[^:]++(?:::[^:]++(?=::))*+(?=::[^:]*+\z)/]
+    end.select do |_, klasses|
+      klasses.any?(&:display?)
+    end
+
+    grouped_classes.values.each(&:uniq!)
+    grouped_classes
+  end
+
+  private
+
+  def nesting_namespaces_to_class_modules klass
+    tree = {}
+
+    klass.nesting_namespaces.zip(klass.fully_qualified_nesting_namespaces) do |ns, fqns|
+      tree[ns] = @store.classes_hash[fqns] || @store.modules_hash[fqns]
+    end
+
+    tree
+  end
+
+  def generate_nesting_namespaces_breadcrumb klass, rel_prefix
+    nesting_namespaces_to_class_modules(klass).map do |namespace, class_module|
+      path = class_module ? (rel_prefix + class_module.path).to_s : ""
+      { name: namespace, path: path, self: klass.full_name == class_module&.full_name }
+    end
+  end
 end