# File lib/rdoc/generator/aliki.rb, line 88
def initialize(store, options)
  @store   = store
  @options = options

  @asset_rel_path = ''
  @base_dir       = Pathname.pwd.expand_path
  @dry_run        = @options.dry_run
  @file_output    = true
  @template_dir   = Pathname.new(@options.template_dir)
  @template_cache = {}

  @classes = nil
  @context = nil
  @files   = nil
  @methods = nil
  @modsort = nil
end

Initialize a few instance variables before we start

Public Instance Methods

assemble_template (body_file)

Source

# File lib/rdoc/generator/aliki.rb, line 525
  def assemble_template(body_file)
    body = body_file.read
    return body if body =~ /<html/

    head_file = @template_dir + '_head.rhtml'

    <<-TEMPLATE
<!DOCTYPE html>

<html lang="#{@options.locale&.name || 'en'}">
<head>
#{head_file.read}

#{body}
    TEMPLATE
  end

Creates a template from its components and the body_file.

For backwards compatibility, if body_file contains “<html” the body is used directly.

build_search_index ()

Source

# File lib/rdoc/generator/aliki.rb, line 733
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

Build a search index array for Aliki’s searcher.

copy_static ()

Source

# File lib/rdoc/generator/aliki.rb, line 173
def copy_static
  return if @options.static_path.empty?

  fu_options = { :verbose => $DEBUG_RDOC, :noop => @dry_run }

  @options.static_path.each do |path|
    unless File.directory? path then
      FileUtils.install path, @outputdir, **fu_options.merge(:mode => 0644)
      next
    end

    Dir.chdir path do
      Dir[File.join('**', '*')].each do |entry|
        dest_file = @outputdir + entry

        if File.directory? entry then
          FileUtils.mkdir_p entry, **fu_options
        else
          FileUtils.install entry, dest_file, **fu_options.merge(:mode => 0644)
        end
      end
    end
  end
end

Copies static files from the static_path into the output directory

debug_msg (*msg)

Source

# File lib/rdoc/generator/aliki.rb, line 109
def debug_msg(*msg)
  return unless $DEBUG_RDOC
  $stderr.puts(*msg)
end

Output progress information if debugging is enabled

excerpt (comment)

Source

# File lib/rdoc/generator/aliki.rb, line 640
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

Returns an excerpt of the comment for usage in meta description tags

gen_sub_directories ()

Source

# File lib/rdoc/generator/aliki.rb, line 118
def gen_sub_directories
  @outputdir.mkpath
end

Create the directories the generated docs will live in if they don’t already exist.

generate ()

Source

# File lib/rdoc/generator/aliki.rb, line 150
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

Build the initial indices and output objects based on an array of TopLevel objects containing the extracted information.

generate_ancestor_list (ancestors, klass)

Source

# File lib/rdoc/generator/aliki.rb, line 668
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

generate_class (klass, template_file = nil)

Source

# File lib/rdoc/generator/aliki.rb, line 246
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'

  debug_msg "  working on %s (%s)" % [klass.full_name, klass.path]
  out_file   = @outputdir + klass.path
  rel_prefix = @outputdir.relative_path_from out_file.dirname
  search_index_rel_prefix = rel_prefix
  search_index_rel_prefix += @asset_rel_path if @file_output

  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|
    here = binding
    # suppress 1.9.3 warning
    here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
    here
  end
ensure
  @inside_class_file = false
end

Generates a class file for klass

generate_class_files ()

Source

# File lib/rdoc/generator/aliki.rb, line 280
def generate_class_files
  template_file = @template_dir + 'class.rhtml'
  template_file = @template_dir + 'classpage.rhtml' unless
    template_file.exist?
  return unless template_file.exist?
  debug_msg "Generating class documentation in #{@outputdir}"

  current = nil

  # 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
  end
rescue => e
  error = RDoc::Error.new \
    "error generating #{current.path}: #{e.message} (#{e.class})"
  error.set_backtrace e.backtrace

  raise error
end

Generate a documentation file for each class and module

generate_class_index_content (classes, rel_prefix)

Source

# File lib/rdoc/generator/aliki.rb, line 694
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

generate_class_link (klass, rel_prefix)

Source

# File lib/rdoc/generator/aliki.rb, line 686
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

generate_file_files ()

Source

# File lib/rdoc/generator/aliki.rb, line 307
def generate_file_files
  page_file     = @template_dir + 'page.rhtml'
  fileinfo_file = @template_dir + 'fileinfo.rhtml'

  # for legacy templates
  filepage_file = @template_dir + 'filepage.rhtml' unless
    page_file.exist? or fileinfo_file.exist?

  return unless
    page_file.exist? or fileinfo_file.exist? or filepage_file.exist?

  debug_msg "Generating file documentation in #{@outputdir}"

  out_file = nil
  current = nil

  @files.each do |file|
    current = file

    if file.text? and page_file.exist? then
      generate_page file
      next
    end

    template_file = nil
    out_file = @outputdir + file.path
    debug_msg "  working on %s (%s)" % [file.full_name, out_file]
    rel_prefix = @outputdir.relative_path_from out_file.dirname
    search_index_rel_prefix = rel_prefix
    search_index_rel_prefix += @asset_rel_path if @file_output

    asset_rel_prefix = rel_prefix + @asset_rel_path

    unless filepage_file then
      if file.text? then
        next unless page_file.exist?
        template_file = page_file
        @title = file.page_name
      else
        next unless fileinfo_file.exist?
        template_file = fileinfo_file
        @title = "File: #{file.base_name}"
      end
    end

    @title += " - #{@options.title}"
    template_file ||= filepage_file

    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 =
    RDoc::Error.new "error generating #{out_file}: #{e.message} (#{e.class})"
  error.set_backtrace e.backtrace

  raise error
end

Generate a documentation file for each file

generate_index ()

Source

# File lib/rdoc/generator/aliki.rb, line 211
def generate_index
  template_file = @template_dir + 'index.rhtml'
  return unless template_file.exist?

  debug_msg "Rendering the index page..."

  out_file = @base_dir + @options.op_dir + 'index.html'
  rel_prefix = @outputdir.relative_path_from out_file.dirname
  search_index_rel_prefix = rel_prefix
  search_index_rel_prefix += @asset_rel_path if @file_output

  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
  error = RDoc::Error.new \
    "error generating index.html: #{e.message} (#{e.class})"
  error.set_backtrace e.backtrace

  raise error
end

Generate an index page which lists all the classes which are documented.

generate_page (file)

Source

# File lib/rdoc/generator/aliki.rb, line 374
def generate_page(file)
  template_file = @template_dir + 'page.rhtml'

  out_file = @outputdir + file.path
  debug_msg "  working on %s (%s)" % [file.full_name, out_file]
  rel_prefix = @outputdir.relative_path_from out_file.dirname
  search_index_rel_prefix = rel_prefix
  search_index_rel_prefix += @asset_rel_path if @file_output

  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|
    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

Generate a page file for file

generate_servlet_not_found (message)

Source

# File lib/rdoc/generator/aliki.rb, line 401
def generate_servlet_not_found(message)
  template_file = @template_dir + 'servlet_not_found.rhtml'
  return unless template_file.exist?

  debug_msg "Rendering the servlet 404 Not Found page..."

  rel_prefix = rel_prefix = ''
  search_index_rel_prefix = rel_prefix
  search_index_rel_prefix += @asset_rel_path if @file_output

  asset_rel_prefix = ''

  @title = 'Not Found'

  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})"
  error.set_backtrace e.backtrace

  raise error
end

Generates the 404 page for the RDoc servlet

generate_servlet_root (installed)

Source

# File lib/rdoc/generator/aliki.rb, line 432
def generate_servlet_root(installed)
  template_file = @template_dir + 'servlet_root.rhtml'
  return unless template_file.exist?

  debug_msg 'Rendering the servlet root page...'

  rel_prefix = '.'
  asset_rel_prefix = rel_prefix
  search_index_rel_prefix = asset_rel_prefix
  search_index_rel_prefix += @asset_rel_path if @file_output

  @title = 'Local RDoc Documentation'

  render_template template_file do |io| binding end
rescue => e
  error = RDoc::Error.new \
    "error generating servlet_root: #{e.message} (#{e.class})"
  error.set_backtrace e.backtrace

  raise error
end

Generates the servlet root page for the RDoc servlet

generate_table_of_contents ()

Source

# File lib/rdoc/generator/aliki.rb, line 457
def generate_table_of_contents
  template_file = @template_dir + 'table_of_contents.rhtml'
  return unless template_file.exist?

  debug_msg "Rendering the Table of Contents..."

  out_file = @outputdir + 'table_of_contents.html'
  rel_prefix = @outputdir.relative_path_from out_file.dirname
  search_index_rel_prefix = rel_prefix
  search_index_rel_prefix += @asset_rel_path if @file_output

  asset_rel_prefix = rel_prefix + @asset_rel_path

  @title = "Table of Contents - #{@options.title}"

  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})"
  error.set_backtrace e.backtrace

  raise error
end

Generate an index page which lists all the classes which are documented.

get_sorted_module_list (classes)

Source

# File lib/rdoc/generator/aliki.rb, line 202
def get_sorted_module_list(classes)
  classes.select do |klass|
    klass.display?
  end.sort
end

Return a list of the documented modules sorted by salience first, then by name.

group_classes_by_namespace_for_sidebar (classes)

Source

# File lib/rdoc/generator/aliki.rb, line 719
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

render (file_name)

Source

# File lib/rdoc/generator/aliki.rb, line 546
def render(file_name)
  template_file = @template_dir + file_name

  template = template_for template_file, false, RDoc::ERBPartial

  template.filename = template_file.to_s

  template.result @context
end

Renders the ERb contained in file_name relative to the template directory and returns the result based on the current context.

render_template (template_file, out_file = nil) { |io| ... }

Source

# File lib/rdoc/generator/aliki.rb, line 564
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

  template = template_for template_file, true, erb_klass

  if io_output then
    debug_msg "Outputting to %s" % [out_file.expand_path]

    out_file.dirname.mkpath
    out_file.open 'w', 0644 do |io|
      io.set_encoding @options.encoding

      @context = yield io

      template_result template, @context, template_file
    end
  else
    @context = yield nil

    output = template_result template, @context, template_file

    debug_msg "  would have written %d characters to %s" % [
      output.length, out_file.expand_path
    ] if @dry_run

    output
  end
end

Load and render the erb template in the given template_file and write it out to out_file.

Both template_file and out_file should be Pathname-like objects.

An io will be yielded which must be captured by binding in the caller.

resolve_url (rel_prefix, url)

Source

# File lib/rdoc/generator/aliki.rb, line 785
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

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.

setup ()

Source

# File lib/rdoc/generator/aliki.rb, line 506
def setup
  return if instance_variable_defined? :@outputdir

  @outputdir = Pathname.new(@options.op_dir).expand_path @base_dir

  return unless @store

  @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

Prepares for generation of output from the current directory

template_for (file, page = true, klass = ERB)

Source

# File lib/rdoc/generator/aliki.rb, line 611
def template_for(file, page = true, klass = ERB)
  template = @template_cache[file]

  return template if template

  if page then
    template = assemble_template file
    erbout = 'io'
  else
    template = file.read
    template = template.encode @options.encoding

    file_var = File.basename(file).sub(/\..*/, '')

    erbout = "_erbout_#{file_var}"
  end

  template = klass.new template, trim_mode: '-', eoutvar: erbout
  @template_cache[file] = template
  template
end

Retrieves a cache template for file, if present, or fills the cache.

template_result (template, context, template_file)

Source

# File lib/rdoc/generator/aliki.rb, line 598
def template_result(template, context, template_file)
  template.filename = template_file.to_s
  template.result context
rescue NoMethodError => e
  raise RDoc::Error, "Error while evaluating %s: %s" % [
    template_file.expand_path,
    e.message,
  ], e.backtrace
end

Creates the result for template with context. If an error is raised a Pathname template_file will indicate the file where the error occurred.

traverse_classes (klasses, grouped_classes, rel_prefix, solo = false)

Source

# File lib/rdoc/generator/aliki.rb, line 702
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

write_search_index ()

Source

# File lib/rdoc/generator/aliki.rb, line 767
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

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.

write_style_sheet ()

Source

# File lib/rdoc/generator/aliki.rb, line 126
def write_style_sheet
  debug_msg "Copying static files"
  options = { verbose: $DEBUG_RDOC, noop: @dry_run }

  %w[css js fonts images].each do |subdir|
    Dir[(@template_dir + "#{subdir}/**/*").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

  unless @options.template_stylesheets.empty?
    FileUtils.cp @options.template_stylesheets, '.', **options
  end
end

Copy static assets (CSS, JS, fonts) from the template directory to the output directory.