hologram 1.0.1 → 1.1.0

data/lib/hologram/document_block.rb

@@ -1,35 +1,57 @@
 module Hologram
   class DocumentBlock
-    attr_accessor :name, :parent, :children, :title, :category, :markdown, :config, :heading
+    COMMENT_REGEX = /^\s*---\s(.*?)\s---$/m
+
+    attr_accessor :name, :parent, :children, :title, :categories, :markdown, :config, :heading, :errors
 
     def initialize(config = nil, markdown = nil)
       @children = {}
+      @errors = []
       set_members(config, markdown) if config and markdown
     end
 
+    def self.from_comment(comment)
+      comment_match = COMMENT_REGEX.match(comment)
+      return if !comment_match
+
+      markdown = comment.sub(comment_match[0], '')
+      config = YAML::load(comment_match[1])
+
+      self.new(config, markdown)
+    rescue ArgumentError, Psych::SyntaxError
+      raise CommentLoadError, "Could not parse comment:\n#{comment}"
+    end
+
     def set_members(config, markdown)
       @name     = config['name']
-      @category = config['category']
+      @categories = Array(config['category'] || config['categories'])
       @title    = config['title']
       @parent   = config['parent']
       @markdown = markdown
+
+      if @name.nil?
+        @name = @title.gsub(' ', '_')
+      end
     end
 
     def get_hash
       {:name => @name,
        :parent => @parent,
-       :category => @category,
+       :categories => @categories,
        :title => @title
       }
     end
 
     def is_valid?
-      !!(@name && @markdown)
+      errors << 'Missing required category and/or parent config value' if !categories and !parent
+      errors << 'Missing name or title config value' if !name and !title
+      errors << 'Missing required markdown' if !markdown
+      errors.empty?
     end
 
     # sets the header tag based on how deep your nesting is
     def markdown_with_heading(heading = 1)
-      @markdown = "\n\n<h#{heading.to_s} id=\"#{@name}\">#{@title}</h#{heading.to_s}>" + @markdown
+      "\n\n<h#{heading.to_s} id=\"#{@name}\">#{@title}</h#{heading.to_s}>" + @markdown
     end
   end
 end

data/lib/hologram/errors.rb

@@ -0,0 +1,12 @@
+module Hologram
+  class CommentLoadError < StandardError
+  end
+end
+
+module Hologram
+  class NoCategoryError < StandardError
+    def message
+      "Hologram comments found with no defined category. Are there other warnings/errors that need to be resolved?"
+    end
+  end
+end

data/lib/hologram/markdown_renderer.rb

@@ -0,0 +1,49 @@
+module Hologram
+  class MarkdownRenderer < Redcarpet::Render::HTML
+    def block_code(code, language)
+      if language and language.include?('example')
+        if language.include?('js')
+          # first actually insert the code in the docs so that it will run and make our example work.
+          '<script>' + code + '</script>
+          <div class="codeBlock jsExample">' + Pygments.highlight(code) + '</div>'
+        else
+          '<div class="codeExample">' + '<div class="exampleOutput">' + render_html(code, language) + '</div>' + '<div class="codeBlock">' + Pygments.highlight(code, :lexer => get_lexer(language)) + '</div>' + '</div>'
+        end
+      else
+        '<div class="codeBlock">' + Pygments.highlight(code) + '</div>'
+      end
+    end
+
+    private
+    def render_html(code, language)
+      case language
+        when 'haml_example'
+          safe_require('haml', language)
+          return Haml::Engine.new(code.strip).render(template_rendering_scope, {})
+        else
+          code
+      end
+    end
+
+    def template_rendering_scope
+      Object.new
+    end
+
+    def get_lexer(language)
+      case language
+        when 'haml_example'
+          'haml'
+        else
+          'html'
+      end
+    end
+
+    def safe_require(templating_library, language)
+      begin
+        require templating_library
+      rescue LoadError
+        raise "#{templating_library} must be present for you to use #{language}"
+      end
+    end
+  end
+end

data/lib/hologram/template_variables.rb

@@ -2,7 +2,7 @@ module Hologram
 
   #Helper class for binding things for ERB
   class TemplateVariables
-    attr_accessor :title, :file_name, :blocks, :categories
+    attr_accessor :title, :file_name, :blocks, :output_files_by_category, :config, :pages
 
     def initialize(args)
       set_args(args)

data/lib/hologram/utils.rb

@@ -0,0 +1,16 @@
+module Hologram
+  module Utils
+    def self.get_markdown_renderer(custom_markdown = nil)
+      return MarkdownRenderer if custom_markdown.nil?
+
+      load custom_markdown
+      renderer_class = File.basename(custom_markdown, '.rb').split(/_/).map(&:capitalize).join
+      DisplayMessage.info("Custom markdown renderer #{renderer_class} loaded.")
+      Module.const_get(renderer_class)
+    rescue LoadError => e
+      DisplayMessage.error("Could not load #{custom_markdown}.")
+    rescue NameError => e
+      DisplayMessage.error("Class #{renderer_class} not found in #{custom_markdown}.")
+    end
+  end
+end

data/lib/hologram/version.rb

@@ -25,5 +25,5 @@
 # ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 module Hologram
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

data/lib/template/hologram_config.yml

@@ -19,6 +19,6 @@ dependencies:
   - ./build
 
 # Mark which category should be the index page
-# Alternatively, you may have an index.md in the documenatation assets
-# folder instead of specifying this configu.
+# Alternatively, you may have an index.md in the documentation assets
+# folder instead of specifying this config.
 index: basics

data/spec/cli_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+require 'hologram/cli'
+
+describe Hologram::CLI do
+  let(:argv) { [] }
+  subject(:cli) { Hologram::CLI.new(argv) }
+
+  context '#run' do
+    context 'when arg is "init"' do
+      let(:argv) { ['init'] }
+
+      it 'setups the dir' do
+        expect(Hologram::DocBuilder).to receive(:setup_dir)
+        cli.run
+      end
+    end
+
+    context 'when arg is empty' do
+      subject(:builder) { double(Hologram::DocBuilder, is_valid?: true, build: true) }
+
+      it 'builds the documentation' do
+        expect(Hologram::DocBuilder).to receive(:from_yaml).and_return(builder)
+        cli.run
+      end
+    end
+
+    context 'when a config file is passed' do
+      let(:argv) { ['test.yml'] }
+      subject(:builder) { double(Hologram::DocBuilder, is_valid?: true, build: true) }
+
+      it 'builds the documentation' do
+        expect(Hologram::DocBuilder).to receive(:from_yaml).with('test.yml').and_return(builder)
+        cli.run
+      end
+    end
+  end
+end

data/spec/display_message_spec.rb

@@ -4,23 +4,6 @@ require 'tempfile'
 describe Hologram::DisplayMessage do
   subject(:display) { Hologram::DisplayMessage }
 
-  #Rails kernerl helper
-  def capture(stream)
-    stream = stream.to_s
-    captured_stream = Tempfile.new(stream)
-    stream_io = eval("$#{stream}")
-    origin_stream = stream_io.dup
-    stream_io.reopen(captured_stream)
-
-    yield
-
-    stream_io.rewind
-    return captured_stream.read
-  ensure
-    captured_stream.unlink
-    stream_io.reopen(origin_stream)
-  end
-
   context '.quiet!' do
     around do |example|
       display.quiet!

data/spec/doc_block_collection_spec.rb

@@ -32,7 +32,7 @@ comment
   context '#add_doc_block' do
     context 'when the comment is valid' do
       before do
-        collection.add_doc_block(comment)
+        collection.add_doc_block(comment, 'fake_file.sass')
       end
 
       it 'adds a doc block to the collection' do
@@ -42,7 +42,7 @@ comment
 
     context 'when no yaml is provided' do
       before do
-        collection.add_doc_block('')
+        collection.add_doc_block('', 'fake_file.sass')
       end
 
       it 'does not add a new block' do
@@ -54,7 +54,7 @@ comment
   context '#create_nested_structure' do
     context 'when the collection has blocks with parents' do
       before do
-        collection.add_doc_block(comment)
+        collection.add_doc_block(comment, 'fake_file.sass')
         collection.add_doc_block(%q{
           /*doc
           ---
@@ -63,7 +63,7 @@ comment
           parent: button
           ---
           some other button style
-          */})
+          */}, 'fake_file.sass')
 
         collection.create_nested_structure
       end

data/spec/doc_builder_spec.rb

@@ -1,31 +1,18 @@
 require 'spec_helper'
 
 describe Hologram::DocBuilder do
-  subject(:builder) { Hologram::DocBuilder.new }
+  subject(:builder) { Hologram::DocBuilder }
 
-  context '#init' do
-    around do |example|
-      Hologram::DisplayMessage.quiet!
-      example.run
-      Hologram::DisplayMessage.show!
-    end
-
-    context 'when passed an invalid config' do
-      before do
-        File.open('bad_config.yml', 'w'){ |io| io << '%' }
-      end
-
-      after do
-        FileUtils.rm('bad_config.yml')
-      end
+  around do |example|
+    Hologram::DisplayMessage.quiet!
+    example.run
+    Hologram::DisplayMessage.show!
+  end
 
-      it 'exits the process' do
-        expect { builder.init(['bad_config.yml']) }.to raise_error SystemExit
-      end
-    end
+  context '.from_yaml' do
+    subject(:builder) { Hologram::DocBuilder }
 
-    context 'when passed a config file' do
-      let(:style_files) { Dir[File.expand_path('../fixtures/styleguide/**/*.*', __FILE__)] }
+    context 'when passed a valid config file' do
       let(:config_path) { File.join(Dir.pwd, 'spec/fixtures/source/config.yml') }
       let(:config_copy_path) { File.join(Dir.pwd, 'spec/fixtures/source/config.yml.copy') }
 
@@ -43,50 +30,146 @@ describe Hologram::DocBuilder do
         end
       end
 
+      it 'returns a DocBuilder instance' do
+        expect(subject.from_yaml(config_copy_path)).to be_a Hologram::DocBuilder
+      end
+    end
+
+    context 'when passed an invalid config' do
       before do
-        builder.init([config_copy_path])
+        File.open('bad_config.yml', 'w'){ |io| io << '%' }
+      end
+
+      after do
+        FileUtils.rm('bad_config.yml')
+      end
+
+      it 'exits the process' do
+        expect { subject.from_yaml('bad_config.yml') }.to raise_error SyntaxError
       end
+    end
+  end
+
+  context '.setup_dir' do
+    subject(:builder) { Hologram::DocBuilder }
 
-      it 'builds a styleguide' do
-        processed_files = Dir[File.join('.', '**/*.*')]
-        processed_files.each_with_index do |file, index|
-          expect(FileUtils.cmp(file, style_files[index])).to be_true
+    around do |example|
+      Dir.mktmpdir do |dir|
+        Dir.chdir(dir) do
+          example.run
         end
       end
     end
 
-    context 'when passed "init" as arg' do
-      around do |example|
-        Dir.mktmpdir do |dir|
-          Dir.chdir(dir) do
-            example.run
-          end
+    before do
+      builder.setup_dir
+    end
+
+    it 'creates a config file' do
+      expect(File.exists?('hologram_config.yml')).to be_true
+    end
+
+    it 'creates default assets' do
+      Dir.chdir('doc_assets') do
+        ['_header.html', '_footer.html'].each do |asset|
+          expect(File.exists?(asset)).to be_true
         end
       end
+    end
 
-      before do
-        builder.init(['init'])
+    context 'when a hologram_config.yml already exists' do
+      it 'does nothing' do
+        open('hologram_config.yml', 'w') {|io|io << 'foo'}
+        builder.setup_dir
+        expect(IO.read('hologram_config.yml')).to eql('foo')
+      end
+    end
+  end
+
+  context '#is_valid?' do
+
+    let(:config) do
+      {
+        'source' => 'spec/fixtures/source/components',
+        'documentation_assets' => 'spec/fixtures/source/templates',
+        'base_path' => 'spec/fixtures/source/'
+      }
+    end
+
+    let(:builder) { Hologram::DocBuilder.new(config) }
+
+    around do |example|
+      Dir.mktmpdir do |tmpdir|
+        config['destination'] = tmpdir
+        example.run
       end
+    end
 
-      it 'creates a config file' do
-        expect(File.exists?('hologram_config.yml')).to be_true
+    context 'when config vars are present and directories exists' do
+      it 'returns true' do
+        expect(builder.is_valid?).to be_true
       end
+    end
 
-      it 'creates default assets' do
-        Dir.chdir('doc_assets') do
-          ['_header.html', '_footer.html'].each do |asset|
-            expect(File.exists?(asset)).to be_true
-          end
+    ['source', 'destination', 'documentation_assets'].each do |config_var|
+      context "when the required #{config_var} parameter is missing" do
+        before do
+          config.delete(config_var)
+        end
+
+        it 'returns false' do
+          expect(builder.is_valid?).to be_false
         end
-      end
 
-      context 'when a hologram_config.yml already exists' do
-        it 'does nothing' do
-          open('hologram_config.yml', 'w') {|io|io << 'foo'}
-          builder.init(['init'])
-          expect(IO.read('hologram_config.yml')).to eql('foo')
+        it 'populates errors' do
+          builder.is_valid?
+          expect(builder.errors.size).to eql 1
         end
       end
     end
+
+    context "when the source directory does not exist" do
+      before do
+        config['source'] = './foo'
+      end
+
+      it 'returns false' do
+        expect(builder.is_valid?).to be_false
+      end
+
+      it 'populates errors' do
+        builder.is_valid?
+        expect(builder.errors.size).to eql 1
+      end
+    end
+  end
+
+  context '#build' do
+    let(:style_files) { Dir[File.expand_path('../fixtures/styleguide/**/*.*', __FILE__)] }
+    let(:processed_files) { Dir[File.join(builder.destination, '.', '**/*.*')] }
+    let(:config_path) { File.join(Dir.pwd, 'spec/fixtures/source/config.yml') }
+    let(:config_copy_path) { File.join(Dir.pwd, 'spec/fixtures/source/config.yml.copy') }
+    let(:builder) { Hologram::DocBuilder.from_yaml(config_copy_path) }
+
+    around do |example|
+      Dir.mktmpdir do |tmpdir|
+        FileUtils.cp(config_path, config_copy_path)
+        File.open(config_copy_path, 'a'){ |io| io << "destination: #{tmpdir}" }
+        current_dir = Dir.pwd
+        Dir.chdir('spec/fixtures/source')
+
+        example.run
+
+        Dir.chdir(current_dir)
+        FileUtils.rm(config_copy_path)
+      end
+    end
+
+    it 'builds a styleguide' do
+      builder.build
+      style_files.each_with_index do |file, index|
+        expect(FileUtils.cmp(file, processed_files[index])).to be_true
+      end
+    end
   end
 end