rdoc-generator-solarfish 0.0.2

data/lib/rdoc/generator/theme_loader.rb

@@ -0,0 +1,160 @@
+require 'fileutils'
+require 'yaml'
+require 'sass'
+
+require_relative 'settings'
+
+# ThemeLoader reads theme files from `.yml' files and builds a hash that
+# will be passed to HTML template or written to JSON file, and a list
+# of theme files to be installed along with the HTML file.
+class ThemeLoader
+  def self.themes_list
+    Settings.list_file_names 'themes', '.yml'
+  end
+
+  def self.theme_path(name)
+    Settings.find_file 'themes', '.yml', name
+  end
+
+  def initialize(options)
+    @options = options
+  end
+
+  def load
+    theme = {
+      head: {
+        styles:  [],
+        fonts:   [],
+        scripts: [],
+        html:    []
+      },
+      body: {
+        header: [],
+        footer: []
+      }
+    }
+
+    theme_files = []
+
+    @options.sf_themes.each do |theme_path|
+      load_theme(theme, theme_files, theme_path)
+    end
+
+    build_files(theme_files)
+
+    [theme, theme_files]
+  end
+
+  private
+
+  def load_theme(theme, theme_files, theme_path)
+    config = YAML.load_file theme_path
+
+    config.each do |section, content|
+      check_one_of(
+        message:  'Unexpected section in theme config',
+        expected: %w[head body],
+        actual:   section
+      )
+
+      case section
+      when 'head'
+        content.each do |key, files|
+          check_one_of(
+            message:  "Unexpected key in 'head'",
+            expected: %w[styles fonts scripts html],
+            actual:   key
+          )
+          section = key.to_sym
+          files.each do |file_info|
+            path = theme_file(theme_path, file_info['file'])
+            case section
+            when :styles, :scripts, :fonts
+              name = File.basename(path)
+              fh = {
+                url: theme_url(name)
+              }
+              fh[:family] = file_info['family'] if section == :fonts
+              fp = {
+                src_path: path,
+                dst_name: name,
+                dst_info: fh
+              }
+            when :html
+              fh = {
+                data: File.read(path)
+              }
+            end
+            theme[:head][section] << fh
+            theme_files << fp if fp
+          end
+        end
+
+      when 'body'
+        content.each do |key, files|
+          check_one_of(
+            message:  "Unexpected key in 'body'",
+            expected: %w[header footer],
+            actual:   key
+          )
+          files.each do |file_info|
+            path = theme_file(theme_path, file_info['file'])
+            fh = {
+              data: File.read(path)
+            }
+            theme[:body][key.to_sym] << fh
+          end
+        end
+      end
+    end
+  rescue => error
+    raise "Can't load theme - #{theme_path}\n#{error}"
+  end
+
+  def build_files(theme_files)
+    theme_files.each do |file|
+      ext = File.extname file[:src_path]
+      build_css_file file, ext if %w[.sass .scss].include? ext
+    end
+  end
+
+  def build_css_file(file, ext)
+    options = {
+      cache:  false,
+      style:  :default
+    }
+
+    options[:syntax] = if ext == '.sass'
+                         :sass
+                       else
+                         :scss
+                       end
+
+    input_data = File.read(file[:src_path])
+    renderer = Sass::Engine.new(input_data, options)
+    output_data = renderer.render
+
+    file.delete(:src_path)
+    file[:dst_name] = File.basename(file[:dst_name], '.*') + '.css'
+    file[:dst_info][:url] = theme_url(file[:dst_name])
+    file[:data] = output_data
+  end
+
+  def theme_file(theme_path, file_path)
+    File.join(File.dirname(theme_path), file_path)
+  end
+
+  def theme_url(name)
+    url = @options.sf_prefix || ''
+    url += '/' if !url.empty? && !url.end_with?('/')
+    url + name
+  end
+
+  def check_one_of(message: '', expected: [], actual: '')
+    unless expected.include?(actual)
+      raise %(#{message}: ) +
+            %(got '#{actual}', ) +
+            %(expected one of: #{expected.map { |e| "'#{e}'" }.join(', ')})
+    end
+  end
+end

data/lib/solarfish.rb

@@ -0,0 +1,2 @@
+require 'rdoc/rdoc'
+require 'rdoc/generator/solarfish'

data/rdoc-generator-solarfish.gemspec

@@ -0,0 +1,31 @@
+lib = File.expand_path('lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.name        = 'rdoc-generator-solarfish'
+  spec.version     = '0.0.2'
+  spec.authors     = ['Victor Gaydov', 'Dmitriy Shilin', 'Valeria Khomyakova']
+  spec.email       = ['victor@enise.org']
+  spec.description = 'Single page HTML5 generator for Ruby RDoc'
+  spec.summary     = 'Exposes a new HTML formatter for RDoc'
+  spec.homepage    = 'https://github.com/rbdoc/rdoc-generator-solarfish'
+  spec.license     = 'MIT'
+
+  spec.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.3'
+
+  spec.add_runtime_dependency 'rdoc', '~> 5.1'
+  spec.add_runtime_dependency 'sass', '~> 3.4'
+  spec.add_runtime_dependency 'slim', '~> 3.0'
+  spec.add_runtime_dependency 'recursive-open-struct', '~> 1.0'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake', '~> 12.0'
+  spec.add_development_dependency 'rubocop', '~> 0.49'
+  spec.add_development_dependency 'minitest', '~> 5.10'
+  spec.add_development_dependency 'html5_validator', '~> 1.0'
+end

data/test/test_generator.rb

@@ -0,0 +1,95 @@
+require 'html5_validator/validator'
+require 'pp'
+require 'json'
+
+require 'minitest'
+require 'minitest/autorun'
+
+require 'rdoc/rdoc'
+require 'rdoc/generator/solarfish'
+
+require_relative 'themes'
+
+class TestGenerator < MiniTest::Test
+  def source_file
+    File.join(File.dirname(__FILE__), '../docs/example.rb')
+  end
+
+  def run_generator(file, title)
+    dir = File.join(Dir.mktmpdir, 'out')
+
+    options = RDoc::Options.new
+    options.setup_generator 'solarfish'
+
+    options.verbosity = 0
+    options.files = [file]
+    options.op_dir = dir
+    options.title = title
+
+    options.sf_htmlfile = 'test.html'
+    options.sf_jsonfile = 'test.json'
+
+    yield options if block_given?
+
+    rdoc = RDoc::RDoc.new
+    rdoc.document options
+
+    html = File.read(File.join(dir, 'test.html'))
+    json = File.read(File.join(dir, 'test.json'))
+
+    [html, json]
+  end
+
+  def check_generator(&block)
+    html, json = run_generator(source_file, 'test title', &block)
+
+    validator = Html5Validator::Validator.new
+    validator.validate_text(html)
+
+    flunk validator.errors.pretty_inspect unless validator.valid?
+
+    JSON.parse json
+  end
+
+  def test_defaults
+    check_generator
+  end
+
+  def test_prefix
+    check_generator do |options|
+      options.sf_prefix = '/test_prefix'
+    end
+  end
+
+  def test_template
+    check_generator do |options|
+      options.sf_template = TemplateLoader.template_path(Settings::DEFAULT_TEMPLATE)
+    end
+  end
+
+  def test_themes
+    check_generator do |options|
+      options.sf_themes = [ThemeLoader.theme_path(Settings::DEFAULT_THEME)]
+    end
+    check_generator do |options|
+      options.sf_themes = [Theme1.new.theme_path]
+    end
+    check_generator do |options|
+      options.sf_themes = [Theme2.new.theme_path]
+    end
+    check_generator do |options|
+      options.sf_themes = [Theme1.new.theme_path, Theme2.new.theme_path]
+    end
+  end
+
+  def test_filters
+    check_generator do |options|
+      options.sf_filter_classes = '.*'
+      options.sf_filter_members = '.*'
+    end
+    check_generator do |options|
+      options.sf_filter_classes = 'nevermatch'
+      options.sf_filter_members = 'nevermatch'
+    end
+  end
+end

data/test/test_theme_loader.rb

@@ -0,0 +1,89 @@
+require 'minitest'
+require 'minitest/autorun'
+
+require 'rdoc/generator/theme_loader'
+
+require_relative 'themes'
+
+class TestThemeLoader < MiniTest::Test
+  class Options
+    attr_accessor :sf_themes
+    attr_accessor :sf_prefix
+  end
+
+  def subset?(outer, inner)
+    if outer.is_a?(Hash)
+      inner.each do |k, v|
+        return false unless subset? outer[k], v
+      end
+    elsif outer.is_a?(Array)
+      inner.each do |i|
+        return false unless outer.any? do |o|
+          subset? o, i
+        end
+      end
+    else
+      return false unless outer == inner
+    end
+    return true
+  end
+
+  def load_themes(themes, prefix)
+    options = Options.new
+    options.sf_themes = []
+    options.sf_prefix = prefix
+
+    themes.each do |t|
+      options.sf_themes << t.theme_path
+    end
+
+    theme_loader = ThemeLoader.new(options)
+    theme_loader.load
+  end
+
+  def check_themes_with_prefix(themes: [], in_prefix: '', out_prefix: '')
+    theme, files = load_themes themes, in_prefix
+
+    themes.each do |t|
+      assert subset? theme, t.expected_hash(out_prefix)
+      assert subset? files, t.expected_files
+    end
+  end
+
+  def check_themes(themes)
+    check_themes_with_prefix(
+      themes:     themes,
+      in_prefix:  '',
+      out_prefix: '',
+    )
+    check_themes_with_prefix(
+      themes:     themes,
+      in_prefix:  '/test_prefix',
+      out_prefix: '/test_prefix/',
+    )
+    check_themes_with_prefix(
+      themes:     themes,
+      in_prefix:  '/test_prefix/',
+      out_prefix: '/test_prefix/',
+    )
+  end
+
+  def test_theme1
+    check_themes([
+      Theme1.new,
+    ])
+  end
+
+  def test_theme2
+    check_themes([
+      Theme2.new,
+    ])
+  end
+
+  def test_theme1_theme2
+    check_themes([
+      Theme1.new,
+      Theme2.new,
+    ])
+  end
+end

data/test/themes.rb

@@ -0,0 +1,213 @@
+require 'fileutils'
+
+class BasicTheme
+  def initialize(name)
+    @dir = Dir.mktmpdir
+    @path = File.join(@dir, name)
+  end
+
+  def theme_path
+    @path
+  end
+
+  def file_path(name)
+    File.join(@dir, name)
+  end
+
+  def write_file(name, data)
+    path = file_path(name)
+    FileUtils.mkpath(File.dirname(path))
+    File.write(path, data)
+  end
+end
+
+class Theme1 < BasicTheme
+  def initialize
+    super 'theme1.yml'
+
+    write_file 'theme1.yml', theme_yaml
+
+    write_file 'dir1/style1a.css', ''
+    write_file 'dir2/style1b.sass', ''
+    write_file 'dir2/style1c.scss', ''
+
+    write_file 'dir1/script1a.js', ''
+    write_file 'dir2/script1b.js', ''
+
+    write_file 'dir1/font1a.ttf', ''
+    write_file 'dir2/font1b.ttf', ''
+
+    write_file 'dir1/head1a.html', '<style>h1a</style>'
+    write_file 'dir2/head1b.html', '<style>h1b</style>'
+
+    write_file 'dir1/body1a.html', '<p>b1a</p>'
+    write_file 'dir2/body1b.html', '<p>b1b</p>'
+    write_file 'dir1/body1c.html', '<p>b1c</p>'
+    write_file 'dir2/body1d.html', '<p>b1d</p>'
+  end
+
+  def theme_yaml
+    <<END
+head:
+  styles:
+    -
+      file: dir1/style1a.css
+    -
+      file: dir2/style1b.sass
+    -
+      file: dir2/style1c.scss
+  scripts:
+    -
+      file: dir1/script1a.js
+    -
+      file: dir2/script1b.js
+  fonts:
+    -
+      file: dir1/font1a.ttf
+      family: Family1a
+    -
+      file: dir2/font1b.ttf
+      family: Family1b
+  html:
+    -
+      file: dir1/head1a.html
+    -
+      file: dir2/head1b.html
+body:
+  header:
+    -
+      file: dir1/body1a.html
+    -
+      file: dir2/body1b.html
+  footer:
+    -
+      file: dir1/body1c.html
+    -
+      file: dir2/body1d.html
+END
+  end
+
+  def expected_files
+    [
+      { dst_name: 'style1a.css', src_path: file_path('dir1/style1a.css') },
+      { dst_name: 'style1b.css' },
+      { dst_name: 'style1c.css' },
+
+      { dst_name: 'script1a.js', src_path: file_path('dir1/script1a.js') },
+      { dst_name: 'script1b.js', src_path: file_path('dir2/script1b.js') },
+
+      { dst_name: 'font1a.ttf', src_path: file_path('dir1/font1a.ttf') },
+      { dst_name: 'font1b.ttf', src_path: file_path('dir2/font1b.ttf') },
+    ]
+  end
+
+  def expected_hash(prefix)
+    {
+      :head => {
+        :styles => [
+          { :url => "#{prefix}style1a.css" },
+          { :url => "#{prefix}style1b.css" },
+          { :url => "#{prefix}style1c.css" },
+        ],
+        :scripts => [
+          { :url => "#{prefix}script1a.js" },
+          { :url => "#{prefix}script1b.js" },
+        ],
+        :fonts => [
+          { :url => "#{prefix}font1a.ttf", :family => 'Family1a' },
+          { :url => "#{prefix}font1b.ttf", :family => 'Family1b' },
+        ],
+        :html => [
+          { :data => '<style>h1a</style>' },
+          { :data => '<style>h1b</style>' },
+        ],
+      },
+      :body => {
+        :header => [
+          { :data => '<p>b1a</p>' },
+          { :data => '<p>b1b</p>' },
+        ],
+        :footer => [
+          { :data => '<p>b1c</p>' },
+          { :data => '<p>b1d</p>' },
+        ],
+      }
+    }
+  end
+end
+
+class Theme2 < BasicTheme
+  def initialize
+    super 'theme2.yml'
+
+    write_file 'theme2.yml', theme_yaml
+
+    write_file 'style2a.css', ''
+    write_file 'script2a.js', ''
+    write_file 'font2a.ttf', ''
+    write_file 'head2a.html', '<style>h2a</style>'
+    write_file 'body2a.html', '<p>b2a</p>'
+    write_file 'body2b.html', '<p>b2b</p>'
+  end
+
+  def theme_yaml
+    <<END
+head:
+  styles:
+    -
+      file: style2a.css
+  scripts:
+    -
+      file: script2a.js
+  fonts:
+    -
+      file: font2a.ttf
+      family: Family2a
+  html:
+    -
+      file: head2a.html
+body:
+  header:
+    -
+      file: body2a.html
+  footer:
+    -
+      file: body2b.html
+END
+  end
+
+  def expected_files
+    [
+      { dst_name: 'style2a.css', src_path: file_path('style2a.css') },
+      { dst_name: 'script2a.js', src_path: file_path('script2a.js') },
+      { dst_name: 'font2a.ttf',  src_path: file_path('font2a.ttf') },
+    ]
+  end
+
+  def expected_hash(prefix)
+    {
+      :head => {
+        :styles => [
+          { :url => "#{prefix}style2a.css" },
+        ],
+        :scripts => [
+          { :url => "#{prefix}script2a.js" },
+        ],
+        :fonts => [
+          { :url => "#{prefix}font2a.ttf", :family => 'Family2a' },
+        ],
+        :html => [
+          { :data => '<style>h2a</style>' },
+        ],
+      },
+      :body => {
+        :header => [
+          { :data => '<p>b2a</p>' },
+        ],
+        :footer => [
+          { :data => '<p>b2b</p>' },
+        ],
+      }
+    }
+  end
+end