hologram 1.0.1 → 1.1.0

data/lib/hologram/doc_block_collection.rb

@@ -7,25 +7,15 @@ module Hologram
     end
 
     # this should throw an error if we have a match, but no yaml_match
-    def add_doc_block(comment_block)
-      yaml_match = /^\s*---\s(.*?)\s---$/m.match(comment_block)
-      return unless yaml_match
-
-      markdown = comment_block.sub(yaml_match[0], '')
-
-      begin
-        config = YAML::load(yaml_match[1])
-      rescue
-        DisplayMessage.error("Could not parse YAML:\n#{yaml_match[1]}")
-      end
-
-      if config['name'].nil?
-        DisplayMessage.warning("Missing required name config value. This hologram comment will be skipped. \n #{config.inspect}")
-      else
-        doc_block = DocumentBlock.new(config, markdown)
+    def add_doc_block(comment_block, file_name)
+      doc_block = DocumentBlock.from_comment(comment_block)
+      return unless doc_block
+      if !doc_block.is_valid?
+        skip_block(doc_block, file_name)
+        return
       end
 
-      @doc_blocks[doc_block.name] = doc_block if doc_block.is_valid?
+      @doc_blocks[doc_block.name] = doc_block
     end
 
     def create_nested_structure
@@ -35,14 +25,27 @@ module Hologram
         next if !doc_block.parent
 
         parent = @doc_blocks[doc_block.parent]
-        parent.children[doc_block.name] = doc_block
-        doc_block.parent = parent
-        blocks_to_remove_from_top_level << doc_block.name
+        if parent.nil?
+          DisplayMessage.warning("Hologram comment refers to parent: #{doc_block.parent}, but no other hologram comment has name: #{doc_block.parent}, skipping." )
+        else
+          parent.children[doc_block.name] = doc_block
+          doc_block.parent = parent
+
+          if doc_block.categories.empty?
+            doc_block.categories = parent.categories
+          end
+
+          blocks_to_remove_from_top_level << doc_block.name
+        end
       end
 
       blocks_to_remove_from_top_level.each do |key|
         @doc_blocks.delete(key)
       end
     end
+
+    def skip_block(doc_block, file_name)
+      DisplayMessage.warning(doc_block.errors.join("\n") << " in #{file_name}. This hologram comment will be skipped.")
+    end
   end
 end

data/lib/hologram/doc_builder.rb

@@ -1,203 +1,208 @@
 module Hologram
   class DocBuilder
-    attr_accessor :doc_blocks, :config, :pages
+    attr_accessor :source, :destination, :documentation_assets, :dependencies, :index, :base_path, :renderer, :doc_blocks, :pages, :config_yml
+    attr_reader :errors
+    attr :doc_assets_dir, :output_dir, :input_dir, :header_erb, :footer_erb
 
-    def init(args)
-      @pages = {}
+    def self.from_yaml(yaml_file)
 
-      begin
-        if args[0] == 'init' then
-          if File.exists?("hologram_config.yml")
-            DisplayMessage.warning("Cowardly refusing to overwrite existing hologram_config.yml")
-          else
-            FileUtils.cp_r INIT_TEMPLATE_FILES, Dir.pwd
-            new_files = ["hologram_config.yml", "doc_assets/", "doc_assets/_header.html", "doc_assets/_footer.html"]
-            DisplayMessage.created(new_files)
-          end
-        else
-          begin
-            config_file = args[0] ? args[0] : 'hologram_config.yml'
-
-            begin
-              @config = YAML::load_file(config_file)
-            rescue SyntaxError => e
-              DisplayMessage.error("Could not load config file, check the syntax or try 'hologram init' to get started")
-            rescue
-              DisplayMessage.error("Could not load config file, try 'hologram init' to get started")
-            end
-
-            if @config.is_a? Hash
-
-              validate_config
-
-              current_path = Dir.pwd
-              base_path = Pathname.new(config_file)
-              Dir.chdir(base_path.dirname)
-
-              # the real work happens here.
-              build_docs
-
-              Dir.chdir(current_path)
-              DisplayMessage.success("Build completed. (-: ")
-            else
-              DisplayMessage.error("Could not read config file, check the syntax or try 'hologram init' to get started")
-            end
-          rescue RuntimeError => e
-            DisplayMessage.error("#{e}")
-          end
-        end
-      end
-    end
+      #Change dir so that our paths are relative to the config file
+      base_path = Pathname.new(yaml_file)
+      yaml_file = base_path.realpath.to_s
+      Dir.chdir(base_path.dirname)
 
+      config = YAML::load_file(yaml_file)
+      raise SyntaxError if !config.is_a? Hash
 
-    private
-    def build_docs
-      # Create the output directory if it doesn't exist
-      FileUtils.mkdir_p(config['destination']) unless File.directory?(config['destination'])
-
-      begin
-        input_directory  = Pathname.new(config['source']).realpath
-      rescue
-        DisplayMessage.error("Can not read source directory (#{config['source'].inspect}), does it exist?")
-      end
+      new(config.merge(
+        'config_yml' => config,
+        'base_path' => Pathname.new(yaml_file).dirname,
+        'renderer' => Utils.get_markdown_renderer(config['custom_markdown'])
+      ))
 
-      output_directory = Pathname.new(config['destination']).realpath
-      doc_assets       = Pathname.new(config['documentation_assets']).realpath unless !File.directory?(config['documentation_assets'])
+    rescue SyntaxError, ArgumentError, Psych::SyntaxError
+      raise SyntaxError, "Could not load config file, check the syntax or try 'hologram init' to get started"
+    end
 
-      if doc_assets.nil?
-        DisplayMessage.warning("Could not find documentation assets at #{config['documentation_assets']}")
+    def self.setup_dir
+      if File.exists?("hologram_config.yml")
+        DisplayMessage.warning("Cowardly refusing to overwrite existing hologram_config.yml")
+        return
       end
 
-      doc_parser = DocParser.new(input_directory, config['index'])
-      @pages, @categories = doc_parser.parse
+      FileUtils.cp_r INIT_TEMPLATE_FILES, Dir.pwd
+      new_files = ["hologram_config.yml", "doc_assets/", "doc_assets/_header.html", "doc_assets/_footer.html"]
+      DisplayMessage.created(new_files)
+    end
 
-      if config['index'] && !@pages.has_key?(config['index'] + '.html')
-        DisplayMessage.warning("Could not generate index.html, there was no content generated for the category #{config['index']}.")
-      end
+    def initialize(options)
+      @pages = {}
+      @errors = []
+      @dependencies = options.fetch('dependencies', [])
+      @index = options['index']
+      @base_path = options.fetch('base_path', Dir.pwd)
+      @renderer = options.fetch('renderer', MarkdownRenderer)
+      @source = options['source']
+      @destination = options['destination']
+      @documentation_assets = options['documentation_assets']
+      @config_yml = options['config_yml']
+    end
 
-      write_docs(output_directory, doc_assets)
-
-      # Copy over dependencies
-      if config['dependencies']
-        config['dependencies'].each do |dir|
-          begin
-            dirpath  = Pathname.new(dir).realpath
-            if File.directory?("#{dir}")
-              `rm -rf #{output_directory}/#{dirpath.basename}`
-              `cp -R #{dirpath} #{output_directory}/#{dirpath.basename}`
-            end
-          rescue
-            DisplayMessage.warning("Could not copy dependency: #{dir}")
-          end
-        end
-      end
+    def build
+      set_dirs
+      return false if !is_valid?
 
-      if !doc_assets.nil?
-        Dir.foreach(doc_assets) do |item|
-         # ignore . and .. directories and files that start with
-         # underscore
-         next if item == '.' or item == '..' or item.start_with?('_')
-         `rm -rf #{output_directory}/#{item}`
-         `cp -R #{doc_assets}/#{item} #{output_directory}/#{item}`
-        end
+      set_header_footer
+      current_path = Dir.pwd
+      Dir.chdir(base_path)
+      # Create the output directory if it doesn't exist
+      if !output_dir
+        FileUtils.mkdir_p(destination)
+        set_dirs #need to reset output_dir post-creation for build_docs.
       end
+      # the real work happens here.
+      build_docs
+      Dir.chdir(current_path)
+      DisplayMessage.success("Build completed. (-: ")
+      true
     end
 
+    def is_valid?
+      errors.clear
+      set_dirs
+      errors << "No source directory specified in the config file" if !source
+      errors << "No destination directory specified in the config" if !destination
+      errors << "No documentation assets directory specified" if !documentation_assets
+      errors << "Can not read source directory (#{source}), does it exist?" if source && !input_dir
+      errors.empty?
+    end
 
-    def write_docs(output_directory, doc_assets)
-      # load the markdown renderer we are going to use
-      renderer = get_markdown_renderer
+    private
 
-      if File.exists?("#{doc_assets}/_header.html")
-        header_erb = ERB.new(File.read("#{doc_assets}/_header.html"))
-      elsif File.exists?("#{doc_assets}/header.html")
-        header_erb = ERB.new(File.read("#{doc_assets}/header.html"))
-      else
-        header_erb = nil
-        DisplayMessage.warning("No _header.html found in documentation assets. Without this your css/header will not be included on the generated pages.")
-      end
+    def set_dirs
+      @output_dir = real_path(destination)
+      @doc_assets_dir = real_path(documentation_assets)
+      @input_dir = real_path(source)
+    end
 
-      if File.exists?("#{doc_assets}/_footer.html")
-        footer_erb = ERB.new(File.read("#{doc_assets}/_footer.html"))
-      elsif File.exists?("#{doc_assets}/footer.html")
-        footer_erb = ERB.new(File.read("#{doc_assets}/footer.html"))
-      else
-        footer_erb = nil
-        DisplayMessage.warning("No _footer.html found in documentation assets. This might be okay to ignore...")
-      end
+    def real_path(dir)
+      return if !File.directory?(String(dir))
+      Pathname.new(dir).realpath
+    end
 
-      tpl_vars = TemplateVariables.new({:categories => @categories})
-      #generate html from markdown
-      @pages.each do |file_name, page|
-        fh = get_fh(output_directory, file_name)
+    def build_docs
+      doc_parser = DocParser.new(input_dir, index)
+      @pages, @categories = doc_parser.parse
 
-        title = page[:blocks].empty? ? "" : page[:blocks][0][:category]
+      if index && !@pages.has_key?(index + '.html')
+        DisplayMessage.warning("Could not generate index.html, there was no content generated for the category #{index}.")
+      end
 
-        tpl_vars.set_args({:title =>title, :file_name => file_name, :blocks => page[:blocks]})
+      warn_missing_doc_assets
+      write_docs
+      copy_dependencies
+      copy_assets
+    end
 
-        # generate doc nav html
-        unless header_erb.nil?
-          fh.write(header_erb.result(tpl_vars.get_binding))
-        end
+    def copy_assets
+      return unless doc_assets_dir
+      Dir.foreach(doc_assets_dir) do |item|
+        # 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}`
+      end
+    end
 
-        # write the docs
+    def copy_dependencies
+      dependencies.each do |dir|
         begin
-          fh.write(renderer.render(page[:md]))
-        rescue Exception => e
-          DisplayMessage.error(e.message)
-        end
-
-        # write the footer
-        unless footer_erb.nil?
-          fh.write(footer_erb.result(tpl_vars.get_binding))
+          dirpath  = Pathname.new(dir).realpath
+          if File.directory?("#{dir}")
+            `rm -rf #{output_dir}/#{dirpath.basename}`
+            `cp -R #{dirpath} #{output_dir}/#{dirpath.basename}`
+          end
+        rescue
+          DisplayMessage.warning("Could not copy dependency: #{dir}")
         end
-
-        fh.close()
       end
     end
 
+    def write_docs
+      markdown = Redcarpet::Markdown.new(renderer, { :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|
+        if file_name.nil?
+          raise NoCategoryError
+        else
+          if page[:blocks] && page[:blocks].empty?
+            title = ''
+          else
+            title, _ = @categories.rassoc(file_name)
+          end
 
-    def get_markdown_renderer
-      if config['custom_markdown'].nil?
-        renderer = Redcarpet::Markdown.new(HologramMarkdownRenderer, { :fenced_code_blocks => true, :tables => true })
-      else
-        begin
-          load config['custom_markdown']
-          renderer_class = File.basename(config['custom_markdown'], '.rb').split(/_/).map(&:capitalize).join
-          DisplayMessage.info("Custom markdown renderer #{renderer_class} loaded.")
-          renderer = Redcarpet::Markdown.new(Module.const_get(renderer_class), { :fenced_code_blocks => true, :tables => true })
-        rescue LoadError => e
-          DisplayMessage.error("Could not load #{config['custom_markdown']}.")
-        rescue NameError => e
-          DisplayMessage.error("Class #{renderer_class} not found in #{config['custom_markdown']}.")
+          tpl_vars.set_args({:title => title, :file_name => file_name, :blocks => page[:blocks]})
+          if page.has_key?(:erb)
+            write_erb(file_name, page[:erb], tpl_vars.get_binding)
+          else
+            write_page(file_name, markdown.render(page[:md]), tpl_vars.get_binding)
+          end
         end
       end
-      renderer
     end
 
+    def write_erb(file_name, content, binding)
+      fh = get_fh(output_dir, file_name)
+      erb = ERB.new(content)
+      fh.write(erb.result(binding))
+    ensure
+      fh.close
+    end
 
-    def validate_config
-      unless @config.key?('source')
-        DisplayMessage.error("No source directory specified in the config file")
-      end
+    def write_page(file_name, body, binding)
+      fh = get_fh(output_dir, file_name)
+      fh.write(header_erb.result(binding)) if header_erb
+      fh.write(body)
+      fh.write(footer_erb.result(binding)) if footer_erb
+    ensure
+      fh.close
+    end
 
-      unless @config.key?('destination')
-        DisplayMessage.error("No destination directory specified in the config")
+    def set_header_footer
+      # load the markdown renderer we are going to use
+
+      if File.exists?("#{doc_assets_dir}/_header.html")
+        @header_erb = ERB.new(File.read("#{doc_assets_dir}/_header.html"))
+      elsif File.exists?("#{doc_assets_dir}/header.html")
+        @header_erb = ERB.new(File.read("#{doc_assets_dir}/header.html"))
+      else
+        @header_erb = nil
+        DisplayMessage.warning("No _header.html found in documentation assets. Without this your css/header will not be included on the generated pages.")
       end
 
-      unless @config.key?('documentation_assets')
-        DisplayMessage.error("No documentation assets directory specified")
+      if File.exists?("#{doc_assets_dir}/_footer.html")
+        @footer_erb = ERB.new(File.read("#{doc_assets_dir}/_footer.html"))
+      elsif File.exists?("#{doc_assets_dir}/footer.html")
+        @footer_erb = ERB.new(File.read("#{doc_assets_dir}/footer.html"))
+      else
+        @footer_erb = nil
+        DisplayMessage.warning("No _footer.html found in documentation assets. This might be okay to ignore...")
       end
     end
 
-
     def get_file_name(str)
-      str = str.gsub(' ', '_').downcase + '.html'
+      str.gsub(' ', '_').downcase + '.html'
     end
 
+    def get_fh(output_dir, output_file)
+      File.open("#{output_dir}/#{output_file}", 'w')
+    end
 
-    def get_fh(output_directory, output_file)
-      File.open("#{output_directory}/#{output_file}", 'w')
+    def warn_missing_doc_assets
+      return if doc_assets_dir
+      DisplayMessage.warning("Could not find documentation assets at #{documentation_assets}")
     end
   end
 end

data/lib/hologram/doc_parser.rb

@@ -1,13 +1,13 @@
 module Hologram
   class DocParser
-    SUPPORTED_EXTENSIONS = ['.css', '.scss', '.less', '.sass', '.styl', '.js', '.md', '.markdown' ]
+    SUPPORTED_EXTENSIONS = ['.css', '.scss', '.less', '.sass', '.styl', '.js', '.md', '.markdown', '.erb' ]
     attr_accessor :source_path, :pages, :doc_blocks
 
     def initialize(source_path, index_name = nil)
       @source_path = source_path
       @index_name = index_name
       @pages = {}
-      @categories = {}
+      @output_files_by_category = {}
     end
 
     def parse
@@ -38,7 +38,7 @@ module Hologram
         end
       end
 
-      return @pages, @categories
+      return @pages, @output_files_by_category
     end
 
     private
@@ -52,7 +52,7 @@ module Hologram
       directories.each do |directory|
         # filter and sort the files in our directory
         files = []
-        Dir.foreach(directory).select{ |file| is_supported_file_type?(file) }.each do |file|
+        Dir.foreach(directory).select{ |file| is_supported_file_type?("#{directory}/#{file}") }.each do |file|
           files << file
         end
         files.sort!
@@ -65,6 +65,8 @@ module Hologram
       files.each do |input_file|
         if input_file.end_with?('md')
           @pages[File.basename(input_file, '.md') + '.html'] = {:md => File.read("#{directory}/#{input_file}"), :blocks => []}
+        elsif input_file.end_with?('erb')
+          @pages[File.basename(input_file, '.erb')] = {:erb => File.read("#{directory}/#{input_file}")}
         else
           process_file("#{directory}/#{input_file}", doc_block_collection)
         end
@@ -84,42 +86,41 @@ module Hologram
       return unless hologram_comments
 
       hologram_comments.each do |comment_block|
-        doc_block_collection.add_doc_block(comment_block[0])
+        doc_block_collection.add_doc_block(comment_block[0], file)
       end
     end
 
     def build_output(doc_blocks, output_file = nil, depth = 1)
-      doc_blocks.sort.map do |key, doc_block|
-
-        # if the doc_block has a category set then use that, this will be
-        # true of all top level doc_blocks. The output file they set will then
-        # be passed into the recursive call for adding children to the output
-        if doc_block.category
-          output_file = get_file_name(doc_block.category)
-          @categories[doc_block.category] = output_file
-        end
-
-        if !@pages.has_key?(output_file)
-          @pages[output_file] = {:md => "", :blocks => []}
-        end
+      return if doc_blocks.nil?
 
-        @pages[output_file][:blocks].push(doc_block.get_hash)
-        @pages[output_file][:md] << doc_block.markdown_with_heading(depth)
+      # sort elements in alphabetical order ignoring case
+      doc_blocks.sort{|a, b| a[0].downcase<=>b[0].downcase}.map do |key, doc_block|
 
-        if doc_block.children
-          depth += 1
-          build_output(doc_block.children, output_file, depth)
-          depth -= 1
+        #doc_blocks are guaranteed to always have categories (top-level have categories, children get parent categories if empty).
+        doc_block.categories.each do |category|
+          output_file = get_file_name(category)
+          @output_files_by_category[category] = output_file
+          add_doc_block_to_page(depth, doc_block, output_file)
         end
+        build_output(doc_block.children, nil, depth + 1)
       end
     end
 
     def is_supported_file_type?(file)
-      SUPPORTED_EXTENSIONS.include?(File.extname(file))
+      SUPPORTED_EXTENSIONS.include?(File.extname(file)) and !Dir.exists?(file)
     end
 
     def get_file_name(str)
       str = str.gsub(' ', '_').downcase + '.html'
     end
+
+    def add_doc_block_to_page(depth, doc_block, output_file)
+      if !@pages.has_key?(output_file)
+        @pages[output_file] = {:md => "", :blocks => []}
+      end
+
+      @pages[output_file][:blocks].push(doc_block.get_hash)
+      @pages[output_file][:md] << doc_block.markdown_with_heading(depth)
+    end
   end
 end