hologram 1.2.0 → 1.3.0

data/lib/hologram/code_example_renderer.rb

@@ -0,0 +1,73 @@
+require 'hologram/code_example_renderer/example'
+require 'hologram/code_example_renderer/template'
+
+module Hologram
+  module CodeExampleRenderer
+    class << self
+      def register(example_type, args)
+        puts "Adding renderer for #{example_type} examples"
+        example_types[example_type] = {
+          example_class: args[:example_class],
+          example_template: args[:example_template],
+          table_template: args[:table_template]
+        }
+      end
+
+      def unregister(example_type)
+        example_types.delete(example_type)
+      end
+
+      def example_class_for(example_type)
+        if example_types.has_key?(example_type)
+          example_types[example_type][:example_class]
+        else
+          Example
+        end
+      end
+
+      def example_template_for(example_type)
+        if example_types.has_key?(example_type)
+          example_types[example_type][:example_template]
+        else
+          [
+            "<div class=\"codeBlock\">",
+            "  <div class=\"highlight\">",
+            "    <pre><%= code_example %></pre>",
+            "  </div>",
+            "</div>",
+          ].join("\n")
+        end
+      end
+
+      def table_template_for(example_type)
+        if example_types.has_key?(example_type)
+          example_types[example_type][:table_template]
+        else
+          nil
+        end
+      end
+
+      def load_renderers_and_templates
+        require 'hologram/code_example_renderer/factory'
+
+        Dir[File.join(File.dirname(__FILE__), 'code_example_renderer', 'renderers', '*.rb')].each do |file|
+          require file
+        end
+
+        if path_to_custom_example_renderers
+          Dir[File.join(path_to_custom_example_renderers, '*.rb')].each do |file|
+            require file
+          end
+        end
+      end
+
+      attr_accessor :path_to_custom_example_renderers
+
+      private
+
+      def example_types
+        @example_types ||= Hash.new
+      end
+    end
+  end
+end

data/lib/hologram/code_example_renderer/example.rb

@@ -0,0 +1,27 @@
+module Hologram
+  module CodeExampleRenderer
+    class Example < Struct.new(:code)
+      def rendered_example
+        code
+      end
+
+      def code_example
+        formatter.format(lexer.lex(code)).strip
+      end
+
+      def get_binding
+        binding
+      end
+
+      private
+
+      def formatter
+        @_formatter ||= Rouge::Formatters::HTML.new(wrap: false)
+      end
+
+      def lexer
+        @_lexer ||= Rouge::Lexer.find_fancy('guess', code)
+      end
+    end
+  end
+end

data/lib/hologram/code_example_renderer/factory.rb

@@ -0,0 +1,60 @@
+require 'hologram/code_example_renderer'
+
+module Hologram
+  module CodeExampleRenderer
+    class Factory
+      def self.define(example_type, &block)
+        definition_proxy = DefinitionProxy.new
+        definition_proxy.instance_eval(&block)
+
+        example_class = Class.new(Example) do
+          if definition_proxy.rendered_example_block
+            define_method :rendered_example do
+              definition_proxy.rendered_example_block.call(code)
+            end
+          end
+
+          private
+
+          if definition_proxy.lexer_block
+            define_method :lexer do
+              definition_proxy.lexer_block.call
+            end
+          end
+        end
+
+        CodeExampleRenderer.register(example_type,
+          example_class: example_class,
+          example_template: Template.new(definition_proxy.example_template_name).template,
+          table_template: Template.new(definition_proxy.table_template_name).template,
+        )
+      end
+    end
+
+    class DefinitionProxy
+      attr_reader :example_template_name, :table_template_name,
+                  :lexer_block, :rendered_example_block
+
+      def example_template(template_name)
+        self.example_template_name = template_name
+      end
+
+      def table_template(template_name)
+        self.table_template_name = template_name
+      end
+
+      def lexer(&block)
+        self.lexer_block = block
+      end
+
+      def rendered_example(&block)
+        self.rendered_example_block = block
+      end
+
+      private
+
+      attr_writer :example_template_name, :table_template_name,
+                  :lexer_block, :rendered_example_block
+    end
+  end
+end

data/lib/hologram/code_example_renderer/renderers/haml_renderer.rb

@@ -0,0 +1,17 @@
+Hologram::CodeExampleRenderer::Factory.define 'haml' do
+  example_template 'markup_example_template'
+  table_template 'markup_table_template'
+  lexer { Rouge::Lexer.find('haml') }
+
+  rendered_example do |code|
+    begin
+      require 'haml'
+    rescue LoadError
+      raise "haml must be present for you to use haml"
+    end
+
+    haml_engine = Haml::Engine.new(code.strip)
+    haml_engine.render(Object.new, {})
+  end
+end
+

data/lib/hologram/code_example_renderer/renderers/html_renderer.rb

@@ -0,0 +1,6 @@
+Hologram::CodeExampleRenderer::Factory.define 'html' do
+  example_template 'markup_example_template'
+  table_template 'markup_table_template'
+  lexer { Rouge::Lexer.find('html') }
+end
+

data/lib/hologram/code_example_renderer/renderers/js_renderer.rb

@@ -0,0 +1,5 @@
+Hologram::CodeExampleRenderer::Factory.define 'js' do
+  example_template 'js_example_template'
+  lexer { Rouge::Lexer.find('js') }
+end
+

data/lib/hologram/code_example_renderer/renderers/jsx_renderer.rb

@@ -0,0 +1,4 @@
+Hologram::CodeExampleRenderer::Factory.define 'jsx' do
+  example_template 'jsx_example_template'
+  lexer { Rouge::Lexer.find('html') }
+end

data/lib/hologram/code_example_renderer/renderers/react_renderer.rb

@@ -0,0 +1,21 @@
+require 'securerandom'
+
+Hologram::CodeExampleRenderer::Factory.define 'react' do
+  example_template 'markup_example_template'
+  table_template 'markup_table_template'
+
+  lexer { Rouge::Lexer.find(:html) }
+
+  rendered_example do |code|
+    div_id = SecureRandom.hex(10)
+    [
+      "<div id=\"#{div_id}\"></div>",
+      "<script type=\"text/jsx\">",
+      "  React.render(",
+      "    #{code.strip},",
+      "    document.getElementById('#{div_id}')",
+      "  );",
+      "</script>"
+    ].join("\n")
+  end
+end

data/lib/hologram/code_example_renderer/renderers/slim_renderer.rb

@@ -0,0 +1,16 @@
+Hologram::CodeExampleRenderer::Factory.define 'slim' do
+  example_template 'markup_example_template'
+  table_template 'markup_table_template'
+  lexer { Rouge::Lexer.find('slim') }
+
+  rendered_example do |code|
+    begin
+      require 'slim'
+    rescue LoadError
+      raise "slim must be present for you to use slim"
+    end
+
+    slim_engine = Slim::Template.new { code.strip }
+    slim_engine.render(Object.new, {})
+  end
+end

data/lib/hologram/code_example_renderer/template.rb

@@ -0,0 +1,33 @@
+module Hologram
+  module CodeExampleRenderer
+    class Template < Struct.new(:template_name)
+      def template
+        return nil if !template_filename
+        File.read(template_filename)
+      end
+
+      class << self
+        attr_accessor :path_to_custom_example_templates
+      end
+
+      private
+
+      def template_filename
+        return nil if !template_name
+        custom_file_exists? ? custom_file : default_file
+      end
+
+      def custom_file_exists?
+        !!self.class.path_to_custom_example_templates && File.file?(custom_file)
+      end
+
+      def custom_file
+        File.join(self.class.path_to_custom_example_templates, "#{template_name}.html.erb")
+      end
+
+      def default_file
+        File.join(File.dirname(__FILE__), '..', '..', 'template', 'code_example_templates', "#{template_name}.html.erb")
+      end
+    end
+  end
+end

data/lib/hologram/display_message.rb

@@ -1,6 +1,7 @@
 module Hologram
   module DisplayMessage
     @@quiet = false
+    @@exit_on_warnings = false
 
     def self.quiet!
       @@quiet = true
@@ -16,6 +17,14 @@ module Hologram
       @@quiet
     end
 
+    def self.exit_on_warnings!
+      @@exit_on_warnings = true
+    end
+
+    def self.continue_on_warnings!
+      @@exit_on_warnings = false
+    end
+
     def self.puts(str)
       return if quiet?
       super(str)
@@ -45,6 +54,10 @@ module Hologram
 
     def self.warning(message)
       puts yellow("Warning: #{message}")
+      if @@exit_on_warnings
+        puts red("Exiting due to warning")
+        exit 1
+      end
     end
 
     def self.success(message)

data/lib/hologram/doc_block_collection.rb

@@ -15,7 +15,11 @@ module Hologram
         return
       end
 
-      @doc_blocks[doc_block.name] = doc_block
+      if @doc_blocks.has_key?(doc_block.name)
+        DisplayMessage.warning("Multiple Hologram comments with name: #{doc_block.name}.")
+      else
+        @doc_blocks[doc_block.name] = doc_block
+      end
       return doc_block
     end
 

data/lib/hologram/doc_builder.rb

@@ -1,3 +1,5 @@
+require 'hologram/link_helper'
+
 module Hologram
   class DocBuilder
     attr_accessor :source, :destination, :documentation_assets, :dependencies, :index, :base_path, :renderer, :doc_blocks, :pages, :config_yml
@@ -31,7 +33,17 @@ module Hologram
       end
 
       FileUtils.cp_r INIT_TEMPLATE_FILES, Dir.pwd
-      new_files = ["hologram_config.yml", "doc_assets/", "doc_assets/_header.html", "doc_assets/_footer.html"]
+      new_files = [
+        "hologram_config.yml",
+        "doc_assets/",
+        "doc_assets/_header.html",
+        "doc_assets/_footer.html",
+        "code_example_templates/",
+        "code_example_templates/markdown_example_template.html.erb",
+        "code_example_templates/markdown_table_template.html.erb",
+        "code_example_templates/js_example_template.html.erb",
+        "code_example_templates/jsx_example_template.html.erb",
+      ]
       DisplayMessage.created(new_files)
     end
 
@@ -47,6 +59,14 @@ module Hologram
       @documentation_assets = options['documentation_assets']
       @config_yml = options['config_yml']
       @plugins = Plugins.new(options.fetch('config_yml', {}), extra_args)
+      @nav_level = options['nav_level'] || 'page'
+      @exit_on_warnings = options['exit_on_warnings']
+      @code_example_templates = options['code_example_templates']
+      @code_example_renderers = options['code_example_renderers']
+
+      if @exit_on_warnings
+        DisplayMessage.exit_on_warnings!
+      end
     end
 
     def build
@@ -112,7 +132,7 @@ module Hologram
     end
 
     def build_docs
-      doc_parser = DocParser.new(input_dir, index, @plugins)
+      doc_parser = DocParser.new(input_dir, index, @plugins, nav_level: @nav_level)
       @pages, @categories = doc_parser.parse
 
       if index && !@pages.has_key?(index + '.html')
@@ -131,8 +151,8 @@ module Hologram
         # ignore . and .. directories and files that start with
         # underscore
         next if item == '.' or item == '..' or item.start_with?('_')
-        `rm -rf #{output_dir}/#{item}`
-        `cp -R #{doc_assets_dir}/#{item} #{output_dir}/#{item}`
+        FileUtils.rm "#{output_dir}/#{item}", :force => true
+        FileUtils.cp_r "#{doc_assets_dir}/#{item}", "#{output_dir}/#{item}"
       end
     end
 
@@ -141,8 +161,8 @@ module Hologram
         begin
           dirpath  = Pathname.new(dir).realpath
           if File.directory?("#{dir}")
-            `rm -rf #{output_dir}/#{dirpath.basename}`
-            `cp -R #{dirpath} #{output_dir}/#{dirpath.basename}`
+            FileUtils.rm "#{output_dir}/#{dirpath.basename}", :force => true
+            FileUtils.cp_r "#{dirpath}", "#{output_dir}/#{dirpath.basename}"
           end
         rescue
           DisplayMessage.warning("Could not copy dependency: #{dir}")
@@ -151,7 +171,10 @@ module Hologram
     end
 
     def write_docs
-      markdown = Redcarpet::Markdown.new(renderer, { :fenced_code_blocks => true, :tables => true })
+      load_code_example_templates_and_renderers
+
+      renderer_instance = renderer.new(link_helper: link_helper)
+      markdown = Redcarpet::Markdown.new(renderer_instance, { :fenced_code_blocks => true, :tables => true })
       tpl_vars = TemplateVariables.new({:categories => @categories, :config => @config_yml, :pages => @pages})
       #generate html from markdown
       @pages.each do |file_name, page|
@@ -174,6 +197,34 @@ module Hologram
       end
     end
 
+    def load_code_example_templates_and_renderers
+      if @code_example_templates
+        CodeExampleRenderer::Template.path_to_custom_example_templates = real_path(@code_example_templates)
+      end
+
+      if @code_example_renderers
+        CodeExampleRenderer.path_to_custom_example_renderers = real_path(@code_example_renderers)
+      end
+
+      CodeExampleRenderer.load_renderers_and_templates
+    end
+
+    def link_helper
+      @_link_helper ||= LinkHelper.new(@pages.map { |page|
+        if not page[1][:blocks].nil?
+        {
+          name: page[0],
+          component_names: page[1][:blocks].map { |component| component[:name] }
+        }
+        else
+        {
+          name: page[0],
+          component_names: {}
+        }
+        end
+      })
+    end
+
     def write_erb(file_name, content, binding)
       fh = get_fh(output_dir, file_name)
       erb = ERB.new(content)

data/lib/hologram/doc_parser.rb

@@ -1,12 +1,13 @@
 module Hologram
   class DocParser
     SUPPORTED_EXTENSIONS = ['.css', '.scss', '.less', '.sass', '.styl', '.js', '.md', '.markdown', '.erb' ]
-    attr_accessor :source_path, :pages, :doc_blocks
+    attr_accessor :source_path, :pages, :doc_blocks, :nav_level
 
-    def initialize(source_path, index_name = nil, plugins)
+    def initialize(source_path, index_name = nil, plugins=[], opts={})
       @plugins = plugins
       @source_paths = Array(source_path)
       @index_name = index_name
+      @nav_level = opts[:nav_level] || 'page'
       @pages = {}
       @output_files_by_category = {}
     end
@@ -85,9 +86,16 @@ module Hologram
       # .sass: //doc (follow by other lines proceeded by a space)
       # other types: /*doc ... */
       if file.end_with?('.sass')
-        hologram_comments = file_str.scan(/\s*\/\/doc\s*((( [^\n]*\n)|\n)+)/)
+        #For sass strip out leading white spaces after we get the
+        #comment, this fixes haml when using this comment style
+        hologram_comments = file_str.scan(/\s*\/\/doc\s*((( [^\n]*\n)|\n)+)/).map{ |arr| [arr[0].gsub(/^[ \t]{2}/,'')] }
       else
         hologram_comments = file_str.scan(/^\s*\/\*doc(.*?)\*\//m)
+
+        #check if scss file has sass comments
+        if hologram_comments.length == 0 and file.end_with?('.scss')
+          hologram_comments = file_str.scan(/\s*\/\/doc\s*((( [^\n]*\n)|\n)+)/).map{ |arr| [arr[0].gsub(/^[ \t]{2}/,'')] }
+        end
       end
       return unless hologram_comments
 
@@ -133,8 +141,16 @@ module Hologram
         @pages[output_file] = {:md => "", :blocks => []}
       end
 
+
+      if (@nav_level == 'section' && depth == 1) || @nav_level == 'all'
+        include_sub_nav = true
+      else
+        include_sub_nav = false
+      end
+
       @pages[output_file][:blocks].push(doc_block.get_hash)
-      @pages[output_file][:md] << doc_block.markdown_with_heading(depth)
+      @pages[output_file][:md] << doc_block.markdown_with_heading(depth, include_sub_nav: include_sub_nav)
     end
+
   end
 end