rdoc 6.3.4.1 → 8.0.0

data/lib/rdoc/erbio.rb

@@ -20,18 +20,14 @@ class RDoc::ERBIO < ERB
   ##
   # Defaults +eoutvar+ to 'io', otherwise is identical to ERB's initialize
 
-  def initialize str, safe_level = nil, legacy_trim_mode = nil, legacy_eoutvar = 'io', trim_mode: nil, eoutvar: 'io'
-    if RUBY_VERSION >= '2.6'
-      super(str, trim_mode: trim_mode, eoutvar: eoutvar)
-    else
-      super(str, safe_level, legacy_trim_mode, legacy_eoutvar)
-    end
+  def initialize(str, trim_mode: nil, eoutvar: 'io')
+    super(str, trim_mode: trim_mode, eoutvar: eoutvar)
   end
 
   ##
   # Instructs +compiler+ how to write to +io_variable+
 
-  def set_eoutvar compiler, io_variable
+  def set_eoutvar(compiler, io_variable)
     compiler.put_cmd    = "#{io_variable}.write"
     compiler.insert_cmd = "#{io_variable}.write"
     compiler.pre_cmd    = []
@@ -39,4 +35,3 @@ class RDoc::ERBIO < ERB
   end
 
 end
-

data/lib/rdoc/generator/aliki.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+##
+# Aliki theme for RDoc documentation
+#
+# Author: Stan Lo
+#
+
+class RDoc::Generator::Aliki < RDoc::Generator::Darkfish
+  DESCRIPTION = 'HTML generator, written by Stan Lo'
+
+  RDoc::RDoc.add_generator self
+
+  def initialize(store, options)
+    super
+    aliki_template_dir = File.expand_path(File.join(__dir__, 'template', 'aliki'))
+    @template_dir = Pathname.new(aliki_template_dir)
+  end
+
+  ##
+  # Generate documentation. Overrides Darkfish to use Aliki's own search index
+  # instead of the JsonIndex generator.
+
+  def generate
+    setup
+
+    write_style_sheet
+    generate_index
+    generate_class_files
+    generate_file_files
+    generate_table_of_contents
+    write_search_index
+
+    copy_static
+
+  rescue => e
+    debug_msg "%s: %s\n  %s" % [
+      e.class.name, e.message, e.backtrace.join("\n  ")
+    ]
+
+    raise
+  end
+
+  ##
+  # Copy only the static assets required by the Aliki theme. Unlike Darkfish we
+  # don't ship embedded fonts or image sprites, so limit the asset list to keep
+  # generated documentation lightweight.
+
+  def write_style_sheet
+    debug_msg "Copying Aliki static files"
+    options = { verbose: $DEBUG_RDOC, noop: @dry_run }
+
+    install_rdoc_static_file @template_dir + 'css/rdoc.css', "./css/rdoc.css", options
+
+    unless @options.template_stylesheets.empty?
+      FileUtils.cp @options.template_stylesheets, '.', **options
+    end
+
+    Dir[(@template_dir + 'js/**/*').to_s].each do |path|
+      next if File.directory?(path)
+      next if File.basename(path).start_with?('.')
+
+      dst = Pathname.new(path).relative_path_from(@template_dir)
+
+      install_rdoc_static_file @template_dir + path, dst, options
+    end
+  end
+
+  ##
+  # Build a search index array for Aliki's searcher.
+
+  def build_search_index
+    setup
+
+    index = []
+
+    @classes.each do |klass|
+      next unless klass.display?
+
+      index << build_class_module_entry(klass)
+
+      klass.constants.each do |const|
+        next unless const.display?
+
+        index << build_constant_entry(const, klass)
+      end
+    end
+
+    @methods.each do |method|
+      next unless method.display?
+
+      index << build_method_entry(method)
+    end
+
+    index
+  end
+
+  ##
+  # Write the search index as a JavaScript file
+  # Format: var search_data = { index: [...] }
+  #
+  # We still write to a .js instead of a .json because loading a JSON file triggers CORS check in browsers.
+  # And if we simply inspect the generated pages using file://, which is often the case due to lack of the server mode,
+  # the JSON file will be blocked by the browser.
+
+  def write_search_index
+    debug_msg "Writing Aliki search index"
+
+    index = build_search_index
+
+    FileUtils.mkdir_p 'js' unless @dry_run
+
+    search_index_path = 'js/search_data.js'
+    return if @dry_run
+
+    data = { index: index }
+    File.write search_index_path, "var search_data = #{JSON.generate(data)};"
+  end
+
+  ##
+  # Returns the type signature of +method_attr+ as HTML with linked type names.
+  # Returns nil if no type signature is present.
+
+  def type_signature_html(method_attr, from_path)
+    lines = method_attr.type_signature_lines || @store.rbs_signature_for(method_attr)
+    return unless lines
+
+    RDoc::RbsHelper.signature_to_html(
+      lines,
+      lookup: @store.type_name_lookup,
+      from_path: from_path
+    )
+  end
+
+  ##
+  # Resolves a URL for use in templates. Absolute URLs are returned unchanged.
+  # Relative URLs are prefixed with rel_prefix to ensure they resolve correctly from any page.
+
+  def resolve_url(rel_prefix, url)
+    uri = URI.parse(url)
+    if uri.absolute?
+      url
+    else
+      "#{rel_prefix}/#{url}"
+    end
+  rescue URI::InvalidURIError
+    "#{rel_prefix}/#{url}"
+  end
+
+  private
+
+  def build_class_module_entry(klass)
+    type = case klass
+           when RDoc::NormalClass then 'class'
+           when RDoc::NormalModule then 'module'
+           else 'class'
+           end
+
+    entry = {
+      name: klass.name,
+      full_name: klass.full_name,
+      type: type,
+      path: klass.path
+    }
+
+    snippet = klass.search_snippet
+    entry[:snippet] = snippet unless snippet.empty?
+    entry
+  end
+
+  def build_method_entry(method)
+    type = method.singleton ? 'class_method' : 'instance_method'
+
+    entry = {
+      name: method.name,
+      full_name: method.full_name,
+      type: type,
+      path: method.path
+    }
+
+    snippet = method.search_snippet
+    entry[:snippet] = snippet unless snippet.empty?
+    entry
+  end
+
+  def build_constant_entry(const, parent)
+    entry = {
+      name: const.name,
+      full_name: "#{parent.full_name}::#{const.name}",
+      type: 'constant',
+      path: parent.path
+    }
+
+    snippet = const.search_snippet
+    entry[:snippet] = snippet unless snippet.empty?
+    entry
+  end
+end

data/lib/rdoc/generator/darkfish.rb

@@ -73,17 +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
-
-  VERSION = '3'
-
   ##
   # Description of this generator
 
@@ -156,7 +145,7 @@ class RDoc::Generator::Darkfish
   ##
   # Initialize a few instance variables before we start
 
-  def initialize store, options
+  def initialize(store, options)
     @store   = store
     @options = options
 
@@ -179,27 +168,11 @@ class RDoc::Generator::Darkfish
   ##
   # Output progress information if debugging is enabled
 
-  def debug_msg *msg
+  def debug_msg(*msg)
     return unless $DEBUG_RDOC
     $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 +193,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|
@@ -291,7 +264,7 @@ class RDoc::Generator::Darkfish
   # Return a list of the documented modules sorted by salience first, then
   # by name.
 
-  def get_sorted_module_list classes
+  def get_sorted_module_list(classes)
     classes.select do |klass|
       klass.display?
     end.sort
@@ -301,8 +274,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?
 
@@ -316,11 +287,14 @@ class RDoc::Generator::Darkfish
     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|
       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
@@ -334,9 +308,9 @@ class RDoc::Generator::Darkfish
   ##
   # Generates a class file for +klass+
 
-  def generate_class klass, template_file = nil
-    setup
-
+  def generate_class(klass, template_file = nil)
+    # This is used to auto-collapse Pages section on class/module pages
+    @inside_class_file = true
     current = klass
 
     template_file ||= @template_dir + 'class.rhtml'
@@ -348,7 +322,9 @@ class RDoc::Generator::Darkfish
     search_index_rel_prefix += @asset_rel_path if @file_output
 
     asset_rel_prefix = rel_prefix + @asset_rel_path
-    svninfo          = get_svninfo(current)
+
+    breadcrumb = # used in templates
+    breadcrumb = generate_nesting_namespaces_breadcrumb(current, rel_prefix)
 
     @title = "#{klass.type} #{klass.full_name} - #{@options.title}"
 
@@ -357,17 +333,16 @@ class RDoc::Generator::Darkfish
       here = binding
       # suppress 1.9.3 warning
       here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
-      here.local_variable_set(:svninfo, svninfo)
       here
     end
+  ensure
+    @inside_class_file = false
   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?
@@ -376,7 +351,9 @@ class RDoc::Generator::Darkfish
 
     current = nil
 
-    @classes.each do |klass|
+    # Document files are generated only for non-alias classes/modules
+    @classes.reject(&:is_alias_for).each do |klass|
+
       current = klass
 
       generate_class klass, template_file
@@ -393,8 +370,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'
 
@@ -413,6 +388,8 @@ class RDoc::Generator::Darkfish
     @files.each do |file|
       current = file
 
+      next if file.text? && file.full_name == @options.main_page
+
       if file.text? and page_file.exist? then
         generate_page file
         next
@@ -461,9 +438,7 @@ class RDoc::Generator::Darkfish
   ##
   # Generate a page file for +file+
 
-  def generate_page file
-    setup
-
+  def generate_page(file)
     template_file = @template_dir + 'page.rhtml'
 
     out_file = @outputdir + file.path
@@ -490,9 +465,7 @@ class RDoc::Generator::Darkfish
   ##
   # Generates the 404 page for the RDoc servlet
 
-  def generate_servlet_not_found message
-    setup
-
+  def generate_servlet_not_found(message)
     template_file = @template_dir + 'servlet_not_found.rhtml'
     return unless template_file.exist?
 
@@ -523,9 +496,7 @@ class RDoc::Generator::Darkfish
   ##
   # Generates the servlet root page for the RDoc servlet
 
-  def generate_servlet_root installed
-    setup
-
+  def generate_servlet_root(installed)
     template_file = @template_dir + 'servlet_root.rhtml'
     return unless template_file.exist?
 
@@ -551,8 +522,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?
 
@@ -581,7 +550,7 @@ class RDoc::Generator::Darkfish
     raise error
   end
 
-  def install_rdoc_static_file source, destination, options # :nodoc:
+  def install_rdoc_static_file(source, destination, options) # :nodoc:
     return unless source.exist?
 
     begin
@@ -608,62 +577,19 @@ class RDoc::Generator::Darkfish
 
     return unless @store
 
-    @classes = @store.all_classes_and_modules.sort
-    @files   = @store.all_files.sort
-    @methods = @classes.map { |m| m.method_list }.flatten.sort
-    @modsort = get_sorted_module_list @classes
+    refresh_store_data
   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
+  # Refreshes the generator's data from the store.  Called by #setup and
+  # can be called again after the store has been updated (e.g. in server
+  # mode after re-parsing changed files).
 
-  # %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,
-    }
+  def refresh_store_data
+    @classes = @store.all_classes_and_modules.sort
+    @files   = @store.all_files.sort
+    @methods = @classes.flat_map { |m| m.method_list }.sort
+    @modsort = get_sorted_module_list @classes
   end
 
   ##
@@ -672,23 +598,20 @@ class RDoc::Generator::Darkfish
   # For backwards compatibility, if +body_file+ contains "<html" the body is
   # used directly.
 
-  def assemble_template body_file
+  def assemble_template(body_file)
     body = body_file.read
     return body if body =~ /<html/
 
     head_file = @template_dir + '_head.rhtml'
-    footer_file = @template_dir + '_footer.rhtml'
 
     <<-TEMPLATE
 <!DOCTYPE html>
 
-<html>
+<html lang="#{@options.locale&.name || 'en'}">
 <head>
 #{head_file.read}
 
 #{body}
-
-#{footer_file.read}
     TEMPLATE
   end
 
@@ -696,7 +619,7 @@ class RDoc::Generator::Darkfish
   # Renders the ERb contained in +file_name+ relative to the template
   # directory and returns the result based on the current context.
 
-  def render file_name
+  def render(file_name)
     template_file = @template_dir + file_name
 
     template = template_for template_file, false, RDoc::ERBPartial
@@ -714,7 +637,7 @@ class RDoc::Generator::Darkfish
   #
   # An io will be yielded which must be captured by binding in the caller.
 
-  def render_template template_file, out_file = nil # :yield: io
+  def render_template(template_file, out_file = nil) # :yield: io
     io_output = out_file && !@dry_run && @file_output
     erb_klass = io_output ? RDoc::ERBIO : ERB
 
@@ -748,7 +671,7 @@ class RDoc::Generator::Darkfish
   # Creates the result for +template+ with +context+.  If an error is raised a
   # Pathname +template_file+ will indicate the file where the error occurred.
 
-  def template_result template, context, template_file
+  def template_result(template, context, template_file)
     template.filename = template_file.to_s
     template.result context
   rescue NoMethodError => e
@@ -761,7 +684,7 @@ class RDoc::Generator::Darkfish
   ##
   # Retrieves a cache template for +file+, if present, or fills the cache.
 
-  def template_for file, page = true, klass = ERB
+  def template_for(file, page = true, klass = ERB)
     template = @template_cache[file]
 
     return template if template
@@ -778,13 +701,124 @@ class RDoc::Generator::Darkfish
       erbout = "_erbout_#{file_var}"
     end
 
-    if RUBY_VERSION >= '2.6'
-      template = klass.new template, trim_mode: '-', eoutvar: erbout
-    else
-      template = klass.new template, nil, '-', erbout
-    end
+    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 nav-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