rdoc-generator-solarfish 0.0.2

data/lib/rdoc/generator/doc_loader.rb

@@ -0,0 +1,315 @@
+# DocLoader reads RDoc documentation from RDoc store and builds a hash that
+# will be passed to HTML template or written to JSON file.
+class DocLoader
+  def initialize(options, store)
+    @options = options
+    @store = store
+  end
+
+  def load
+    build_classes
+  end
+
+  private
+
+  def build_classes
+    classes = @store.all_classes_and_modules
+
+    classes = classes.reject do |klass|
+      skip_class? klass.full_name
+    end
+
+    class_list = classes.map do |klass|
+      {
+        id:      klass.full_name.strip,
+        title:   klass.full_name,
+        kind:    get_class_kind(klass.full_name),
+        comment: get_comment(klass),
+        groups:  build_groups(klass)
+      }
+    end
+
+    stable_sort_by! class_list do |klass|
+      klass[:id]
+    end
+
+    with_labels class_list
+  end
+
+  def build_groups(klass)
+    members = build_members(klass)
+    groups = {}
+
+    members.each do |member|
+      group = get_builtin_group(member)
+      next unless group
+
+      group_id = make_id(klass, group[:type].to_s)
+
+      unless groups.include? group_id
+        groups[group_id] = group.merge(
+          id: group_id,
+          members: []
+        )
+      end
+
+      groups[group_id][:members] << member
+    end
+
+    group_list = groups.values
+
+    group_list.each do |group|
+      stable_sort_by! group[:members] do |member|
+        member[:id]
+      end
+    end
+
+    stable_sort_by! group_list do |group|
+      builtin_group_order.index group[:type]
+    end
+
+    group_list
+  end
+
+  def build_members(klass)
+    members = []
+
+    method_members = build_members_from_list klass, klass.method_list do |member|
+      member[:kind] = :method
+    end
+
+    attr_members = build_members_from_list klass, klass.attributes do |member|
+      member[:kind] = :attribute
+    end
+
+    const_members = build_members_from_list klass, klass.constants do |member|
+      member[:kind] = :constant
+    end
+
+    extends_members = build_members_from_list klass, klass.extends do |member|
+      member[:kind] = :extended
+    end
+
+    include_members = build_members_from_list klass, klass.includes do |member|
+      member[:kind] = :included
+    end
+
+    members.push(*method_members)
+    members.push(*attr_members)
+    members.push(*const_members)
+    members.push(*extends_members)
+    members.push(*include_members)
+
+    with_labels members
+  end
+
+  def build_members_from_list(klass, member_list)
+    members = []
+
+    member_list.each do |m|
+      next if skip_member? m.name
+
+      member = {}
+
+      member[:id] = make_id(klass, m.name)
+      member[:title] = get_title(m)
+      member[:signature] = get_signature(m)
+      member[:comment] = get_comment(m)
+
+      if m.respond_to? :markup_code
+        member[:code] = m.markup_code if m.markup_code && m.markup_code != ''
+      end
+
+      if m.respond_to? :type
+        member[:level] = m.type.to_sym if m.type
+      end
+
+      if m.respond_to? :visibility
+        member[:visibility] = m.visibility.to_sym if m.visibility
+      end
+
+      yield member
+
+      members << member
+    end
+
+    members
+  end
+
+  def build_labels(object)
+    labels = []
+
+    case object[:kind]
+    when :module, :class, :constant, :included, :extended
+      labels << {
+        id:    object[:kind].capitalize,
+        title: object[:kind].to_s
+      }
+
+    when :method
+      labels << if object[:level] == :class
+                  {
+                    id:    'ClassMethod',
+                    title: 'class method'
+                  }
+                else
+                  {
+                    id:    'InstanceMethod',
+                    title: 'instance method'
+                  }
+                end
+
+    when :attribute
+      labels << if object[:level] == :class
+                  {
+                    id:    'ClassAttribute',
+                    title: 'class attribute'
+                  }
+                else
+                  {
+                    id:    'InstanceAttribute',
+                    title: 'instance attribute'
+                  }
+                end
+    end
+
+    if object[:visibility]
+      labels << {
+        id:    object[:visibility].capitalize,
+        title: object[:visibility].to_s
+      }
+    end
+
+    labels
+  end
+
+  def with_labels(array)
+    array.each do |object|
+      object[:labels] = build_labels(object)
+    end
+    array
+  end
+
+  def make_id(klass, name)
+    klass.full_name.strip + '::' + name
+  end
+
+  def get_title(object)
+    object.name
+  end
+
+  def get_signature(object)
+    if object.respond_to? :arglists
+      return object.arglists if object.arglists
+    end
+    ''
+  end
+
+  def get_comment(object)
+    if object.comment.respond_to? :text
+      object.description.strip
+    else
+      object.comment
+    end
+  end
+
+  def get_class_kind(class_name)
+    if @store.all_modules.select { |m| m.full_name == class_name }.size == 1
+      :module
+    else
+      :class
+    end
+  end
+
+  def builtin_group_order
+    %i[
+      ExtendedClasses
+      IncludedModules
+      Constants
+      ClassAttributes
+      ClassMethods
+      InstanceAttributes
+      InstanceMethods
+    ]
+  end
+
+  def get_builtin_group(member)
+    case member[:kind]
+    when :method
+      case member[:level]
+      when :instance
+        {
+          title: 'Instance Methods',
+          type:  :InstanceMethods,
+          kind:  :method,
+          level: :instance
+        }
+      when :class
+        {
+          title: 'Class Methods',
+          type:  :ClassMethods,
+          kind:  :method,
+          level: :class
+        }
+      end
+    when :attribute
+      case member[:level]
+      when :instance
+        {
+          title: 'Instance Attributes',
+          type:  :InstanceAttributes,
+          kind:  :attribute,
+          level: :instance
+        }
+      when :class
+        {
+          title: 'Class Attributes',
+          type:  :ClassAttributes,
+          kind:  :attribute,
+          level: :class
+        }
+      end
+    when :constant
+      {
+        title: 'Constants',
+        type:  :Constants,
+        kind:  :constant
+      }
+    when :extended
+      {
+        title: 'Extended Classes',
+        type:  :ExtendedClasses,
+        kind:  :extended
+      }
+    when :included
+      {
+        title: 'Included Modules',
+        type:  :IncludedModules,
+        kind:  :included
+      }
+    end
+  end
+
+  def stable_sort_by!(array)
+    sorted = array.each_with_index.sort_by do |e, n|
+      [yield(e), n]
+    end
+    array.replace(sorted.map(&:first))
+  end
+
+  def skip_class?(class_name)
+    if @options.sf_filter_classes
+      @options.sf_filter_classes.match(class_name).nil?
+    else
+      false
+    end
+  end
+
+  def skip_member?(member_name)
+    if @options.sf_filter_members
+      @options.sf_filter_members.match(member_name).nil?
+    else
+      false
+    end
+  end
+end

data/lib/rdoc/generator/html_writer.rb

@@ -0,0 +1,35 @@
+require 'fileutils'
+
+# HTMLWriter builds HTML file from a template and copies HTML and
+# theme files to the output directory.
+class HTMLWriter
+  def initialize(options)
+    @options = options
+  end
+
+  def write(data, theme_files, template)
+    html = template.render(data)
+    install_theme(theme_files)
+    install_html(html)
+  end
+
+  private
+
+  def install_theme(theme_files)
+    theme_files.each do |file|
+      if file[:dst_name]
+        if file[:src_path]
+          FileUtils.copy_file(file[:src_path], file[:dst_name])
+        elsif file[:data]
+          File.write(file[:dst_name], file[:data])
+        end
+      end
+    end
+  end
+
+  def install_html(html)
+    File.open(@options.sf_htmlfile, 'w') do |file|
+      file.write(html)
+    end
+  end
+end

data/lib/rdoc/generator/json_writer.rb

@@ -0,0 +1,16 @@
+require 'json'
+
+# JSONWriter builds JSON file and copies it to the output directory.
+class JSONWriter
+  def initialize(options)
+    @options = options
+  end
+
+  def write(data)
+    json = JSON.pretty_generate(data)
+
+    File.open(@options.sf_jsonfile, 'w') do |file|
+      file.write(json)
+    end
+  end
+end

data/lib/rdoc/generator/settings.rb

@@ -0,0 +1,57 @@
+require 'pathname'
+require 'rubygems'
+
+# Predefined configuration.
+module Settings
+  DEFAULT_HTMLFILE = 'index.html'.freeze
+  DEFAULT_TEMPLATE = 'onepage'.freeze
+  DEFAULT_THEME    = 'light'.freeze
+
+  def self.list_file_names(dir, ext)
+    data_files(dir, "*#{ext}").map do |file|
+      File.basename(file, ext)
+    end
+  end
+
+  def self.find_file(dir, ext, name)
+    if name.include? '/'
+      File.absolute_path name
+    else
+      data_files(dir, "*#{ext}").each do |file|
+        return file if File.basename(file, ext) == name
+      end
+    end
+  end
+
+  def self.data_files(subdir, pattern)
+    files = []
+
+    data_dirs(subdir).each do |dir|
+      pattern = File.join dir, pattern
+
+      Dir[pattern].sort.map do |file|
+        files << file
+      end
+    end
+
+    files.uniq
+  end
+
+  def self.data_dirs(subdir)
+    gemdirs = [
+      Pathname.new(File.join(File.dirname(__FILE__), '../../..')).cleanpath.to_s
+    ]
+    Gem::Specification.each do |spec|
+      gemdirs << spec.full_gem_path
+    end
+
+    datadirs = gemdirs.map do |dir|
+      File.join dir, 'data', 'rdoc-generator-solarfish', subdir
+    end
+    datadirs = datadirs.select do |dir|
+      File.exist? dir
+    end
+
+    datadirs.uniq
+  end
+end

data/lib/rdoc/generator/solarfish.rb

@@ -0,0 +1,135 @@
+require 'rdoc/rdoc'
+
+require_relative 'settings'
+require_relative 'doc_loader'
+require_relative 'theme_loader'
+require_relative 'template_loader'
+require_relative 'json_writer'
+require_relative 'html_writer'
+
+# SolarFish generator options.
+class RDoc::Options
+  attr_accessor :sf_htmlfile
+  attr_accessor :sf_jsonfile
+  attr_accessor :sf_prefix
+  attr_accessor :sf_template
+  attr_accessor :sf_themes
+  attr_accessor :sf_filter_classes
+  attr_accessor :sf_filter_members
+end
+
+# SolarFish generator.
+# Registers command line options and generates HTML and/or JSON output for given
+# RDoc documentation and options.
+class RDoc::Generator::SolarFish
+  RDoc::RDoc.add_generator(self)
+
+  def self.setup_options(rdoc_options)
+    rdoc_options.sf_htmlfile = Settings::DEFAULT_HTMLFILE
+
+    opt = rdoc_options.option_parser
+    opt.separator 'SolarFish generator options:'
+
+    opt.separator nil
+    opt.on('--sf-htmlfile=FILE', String,
+           'Set output HTML file name.',
+           "Defaults to '#{Settings::DEFAULT_HTMLFILE}'.") do |value|
+      rdoc_options.sf_htmlfile = value
+    end
+
+    opt.separator nil
+    opt.on('--sf-jsonfile=FILE', String,
+           'Set output JSON file name.',
+           'Empty by default.') do |value|
+      rdoc_options.sf_jsonfile = value
+    end
+
+    opt.separator nil
+    opt.on('--sf-template=NAME', String,
+           "Set template. Defaults to '#{Settings::DEFAULT_TEMPLATE}'.",
+           "If name contains slash, it's a path, and",
+           "otherwise it's a name of installed template.",
+           'Installed templates:',
+           *(TemplateLoader.templates_list
+             .map { |s| " - #{s}" })) do |value|
+      rdoc_options.sf_template = TemplateLoader.template_path(value)
+    end
+
+    opt.separator nil
+    opt.on('--sf-theme=NAME', String,
+           "Set theme. Defaults to '#{Settings::DEFAULT_THEME}'. Specify",
+           'multiple times to merge several themes. Every',
+           'next theme overwrites options set by previous',
+           "themes. If name contains slash, it's a path,",
+           "and otherwise it's a name of installed theme.",
+           'Installed themes:',
+           *(ThemeLoader.themes_list
+              .map { |s| " - #{s}" })) do |value|
+      rdoc_options.sf_themes ||= []
+      rdoc_options.sf_themes << ThemeLoader.theme_path(value)
+    end
+
+    opt.separator nil
+    opt.on('--sf-prefix=PREFIX', String,
+           'Set URL prefix for links to stylesheets and',
+           'scripts in generated HTML. Empty by default.') do |value|
+      rdoc_options.sf_prefix = value
+    end
+
+    opt.separator nil
+    opt.on('--sf-filter-classes=REGEX', String,
+           'Include only classes and modules that',
+           'match regex.') do |value|
+      rdoc_options.sf_filter_classes = Regexp.new(value)
+    end
+
+    opt.separator nil
+    opt.on('--sf-filter-members=REGEX', String,
+           'Include only members that match regex.') do |value|
+      rdoc_options.sf_filter_members = Regexp.new(value)
+    end
+  end
+
+  def initialize(store, options)
+    @store = store
+    @options = options
+  end
+
+  def class_dir
+    nil
+  end
+
+  def file_dir
+    nil
+  end
+
+  def generate
+    @options.sf_themes ||= [ThemeLoader.theme_path(Settings::DEFAULT_THEME)]
+    @options.sf_template ||= TemplateLoader.template_path(Settings::DEFAULT_TEMPLATE)
+
+    doc_loader = DocLoader.new(@options, @store)
+    classes = doc_loader.load
+
+    theme_loader = ThemeLoader.new(@options)
+    theme, theme_files = theme_loader.load
+
+    data = {
+      title:   @options.title,
+      theme:   theme,
+      classes: classes
+    }
+
+    if @options.sf_jsonfile
+      json_writer = JSONWriter.new(@options)
+      json_writer.write(data)
+    end
+
+    if @options.sf_htmlfile
+      template_loader = TemplateLoader.new(@options)
+      template = template_loader.load
+
+      html_writer = HTMLWriter.new(@options)
+      html_writer.write(data, theme_files, template)
+    end
+  end
+end

data/lib/rdoc/generator/template_loader.rb

@@ -0,0 +1,42 @@
+require 'slim'
+require 'recursive-open-struct'
+
+require_relative 'settings'
+
+# TemplateLoader reads a template from `.slim' file and builds a Template object
+# that may render HTML given a hash with documentation and theme.
+class TemplateLoader
+  def self.templates_list
+    Settings.list_file_names 'templates', '.slim'
+  end
+
+  def self.template_path(name)
+    Settings.find_file 'templates', '.slim', name
+  end
+
+  def initialize(options)
+    @options = options
+  end
+
+  def load
+    Template.new @options.sf_template
+  end
+end
+
+# Template allows to render HTML from a given hash with documentation and theme.
+class Template
+  def initialize(path)
+    @path = path
+  end
+
+  def render(data)
+    opts = {
+      pretty: true
+    }
+
+    vars = RecursiveOpenStruct.new(data, recurse_over_arrays: true)
+
+    template = Slim::Template.new(@path, opts)
+    template.render(vars)
+  end
+end