hologram 0.5.5 → 0.5.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4dc92f494ebbef69183d26491a4402f70eda4905
-  data.tar.gz: 8eb5523c6b4cdcbf52016cbfef86079ce19ec308
+  metadata.gz: e7d3e6ddbc716b6dd6aa6014ca5a07d78a07c888
+  data.tar.gz: efc47c65a4ba7578a446f52d255d0c0f41e6bd42
 SHA512:
-  metadata.gz: 34bab501f8b586ac7cd351111543ca8618a96d065057568d290988aa7a453ea0c2561942800cee4bd76db9404436d829d2d13f0f102dff79195774a696e9c1ff
-  data.tar.gz: 384ffdfe89e4830b6b4bc42a21d4f94d54ad15c31d59c68643ed649e8a4e0292c838c8602956f4c3ed691c98db3c290919e3f24c7bf9dec4125f2cee395c2252
+  metadata.gz: e05fee56543bca4255bd6f690c4e1d5aaf7fa648586d2e262adcc477f9b0581507847f7b019a3dc85369773a1733746bec00c6da74aab72d0981c2eea2fa162e
+  data.tar.gz: 41d73c2d4e16a03c0dfa2a14e7d5738a63584c6b5a40f459edb5c3685883746609bd08d600b72c1df117fb27ee127ddc36413b84fbe4e10fe48e3a9b8ffb9897

data/README.md

@@ -1,8 +1,11 @@
 # Hologram
 
-Hologram is a Ruby gem that parses comments in your CSS and helps you turns them into a beautiful style guide.
+Hologram is a Ruby gem that parses comments in your CSS and helps you turn them into a beautiful style guide.
 
-There are two steps to building a great style guide: 1.) documenting your css and generating html examples, and 2.) actually styling the output of step 1.
+There are two steps to building a great style guide:
+
+1. Documenting your css and generating html examples.
+2. Styling the output of step 1.
 
 The hologram gem itself is only concerned with step 1. This means you are free to make your style guide look however you would like. If you don't feel like going through this process yourself you can take a look at the [templates](https://github.com/trulia/hologram-example/tree/master/templates) in our [example repository](https://github.com/trulia/hologram-example) and use the assets defined there instead.
 
@@ -18,13 +21,30 @@ And then execute:
 
 If you don't use bundler you can run `gem install hologram`.
 
-## Usage
+##Quick Start
+
+```
+hologram init
+```
+
+This will create a config yml file, and also create a starter
+`_header.tpl` and `_footer.tpl` file for you. You can then tweak the
+config values and start documenting your css.
+
+Building the documentation is simply:
+
+```
+hologram
+```
+
+## Details
 
 There are two things you need to do to start using hologram:
 
-1. Create a YAML config file for your project
+1. Create a YAML config file for your project.
+
+2. Go document some code!
 
-2. Document yourself some code
 
 ### Creating a YAML config file
 
@@ -42,19 +62,30 @@ Your config file needs to contain the following key/value pairs
   built to
 
 * **documentation_assets**: The path that contains supporting assets for
-  the documentaiton page. This typically includes html fragments (header/footer, etc),
-  styleguide specific CSS, javascript and any images.
-
-* **custom_markdown**: (optional) this is the filename of a class that extends
-  RedCarpet::Render::HTML class. Use this for when you need
+  the documentaiton page. This typically includes html fragments
+  (header/footer, etc), styleguide specific CSS, javascript and any
+  images. Hologram specifically looks for two files: `_header.html` and
+  `_footer.html`, these are used to start and end every html page
+  holgoram generates. Hologram treats `_header.html` and `_footer.html`
+  as ERB files for each page that is generated you can access the
+  `title`, `file_name`, and `blocks`. `blocks` is a list of each
+  documenation block on the page. Each item in the list has a `title`,
+  `name`, `category`, and optionally a `parent`. Additionaly, filenames
+  that begin with underscores will not be copied into the destination
+  folder.
+
+
+* **custom_markdown**: (optional) this is the filename of a class that
+  extends RedCarpet::Render::HTML class. Use this for when you need
   additional classes or html tags for different parts of the page.
 
-* **index**: (optional) this is a category that will be used as the
-  index.html. 
+* **index**: (optional) this is a category (see **Documenting your styles** section below) that will be used as the
+  index.html.
 
-* **dependencies**: a **list** of relative pathes to a folderes containing any dependencies your style guide has.
-These folders will be copied over into the documentation output directory.
-PUT THE CSS/JS THAT IS ACTUALLY BEING DOCUMENTED HERE
+* **dependencies**: a **list** of relative paths to folders containing
+  any dependencies your style guide has. These folders will be copied
+  over into the documentation output directory. PUT THE CSS/JS THAT IS
+  ACTUALLY BEING DOCUMENTED HERE
 
 ##### Example config file
 
@@ -76,10 +107,9 @@ PUT THE CSS/JS THAT IS ACTUALLY BEING DOCUMENTED HERE
         - ../build
 
 
-
 ###Documenting your styles
 
-Hologram will scan any css/scss/less files within your **source** directory.
+Hologram will scan your .css|.scss|.sass|.less|.styl files within your **source** directory.
 It will look for comments that match the following:
 
     /*doc
@@ -115,8 +145,6 @@ but it specifically looks for the following keys:
 * **title**: The title to display in the documents
 * **category**: This is the broad category for the component, all
   components in the same category will be written to the same page.
-  (Usually named the same as the category but with spaces replaced with
-  underscores and lower cased).
 * **name**: This is used for grouping components, by assigning
   a name a component can be referenced in another component as a parent.
 * **parent**: Optional. If this is set the current component will be
@@ -131,13 +159,6 @@ you'll need for making your style guide look beautiful.
 Hologram doesn't care too much about to what is in here as it is intended
 to be custom for your style guide.
 
-However, it does look for two files called header.html and footer.html.
-These are html fragments that will be used when creating a new category page.
-`header.html` will be copied to the beginning to the page and `footer.html`
-will be copied to the bottom of the page. This gives you control of how you
-will navigate your docs and lets you include any css, disclaimer text, and
-whatever else you need on each page.
-
 #####Styling Your Code Examples
 
 Hologram uses [pygments.rb](https://github.com/tmm1/pygments.rb) gem to provide

data/lib/hologram.rb

@@ -31,11 +31,26 @@ require 'yaml'
 require 'pygments'
 require 'fileutils'
 require 'pathname'
+require 'erb'
 
 require 'hologram_markdown_renderer'
 
 module Hologram
 
+  #Helper class for binding things for ERB
+  class TemplateVariables
+    attr_accessor :title, :file_name, :blocks
+
+    def initialize(title, file_name, blocks)
+      @title = title
+      @file_name = file_name
+      @blocks = blocks
+    end
+
+    def get_binding
+      binding
+    end
+  end
 
   class DocumentBlock
     attr_accessor :name, :parent, :children, :title, :category, :markdown, :output_file, :config
@@ -53,6 +68,14 @@ module Hologram
       @markdown = markdown
     end
 
+    def get_hash
+      {:name => @name,
+       :parent => @parent,
+       :category => @category,
+       :title => @title
+      }
+    end
+
     def is_valid?
       @name && @markdown
     end
@@ -62,27 +85,54 @@ module Hologram
   class Builder
     attr_accessor :doc_blocks, :config, :pages
 
+    INIT_TEMPLATE_PATH = File.expand_path('./template/', File.dirname(__FILE__)) + '/'
+    INIT_TEMPLATE_FILES = [
+      INIT_TEMPLATE_PATH + '/hologram_config.yml',
+      INIT_TEMPLATE_PATH + '/doc_assets',
+    ]
+
     def init(args)
       @doc_blocks, @pages = {}, {}
       @supported_extensions = ['.css', '.scss', '.less', '.sass', '.styl', '.js', '.md', '.markdown' ]
 
       begin
-        @config = args ? YAML::load_file(args[0]) : YAML::load_file('hologram_config.yml')
-        validate_config
-
-        #TODO: maybe this should move into build_docs
-        current_path = Dir.pwd
-        base_path = Pathname.new(args[0])
-        Dir.chdir(base_path.dirname)
-
-        build_docs
-
-        Dir.chdir(current_path)
-        puts "Build successful. (-: ".green
-      rescue Errno::ENOENT
-        display_error("Could not load config file.")
-      rescue RuntimeError => e
-        display_error("#{e}")
+        if args[0] == 'init' then
+
+          if File.exists?("hologram_config.yml")
+            puts "Cowardly refusing to overwrite existing hologram_config.yml"
+          else
+            FileUtils.cp_r INIT_TEMPLATE_FILES, Dir.pwd
+            puts "Created the following files and directories:"
+            puts "  hologram_config.yml"
+            puts "  doc_assets/"
+            puts "  doc_assets/_header.html"
+            puts "  doc_assets/_footer.html"
+          end
+        else
+          begin
+            config_file = args[0] ? args[0] : 'hologram_config.yml'
+
+            begin
+              @config = YAML::load_file(config_file)
+            rescue
+              display_error "Could not load config file, try hologram init to get started"
+            end
+
+            validate_config
+
+            #TODO: maybe this should move into build_docs
+            current_path = Dir.pwd
+            base_path = Pathname.new(config_file)
+            Dir.chdir(base_path.dirname)
+
+            build_docs
+
+            Dir.chdir(current_path)
+            puts "Build completed. (-: ".green
+          rescue RuntimeError => e
+            display_error("#{e}")
+          end
+        end
       end
     end
 
@@ -92,9 +142,13 @@ module Hologram
       # Create the output directory if it doesn't exist
       FileUtils.mkdir_p(config['destination']) unless File.directory?(config['destination'])
 
-      input_directory  = Pathname.new(config['source']).realpath
-      output_directory = Pathname.new(config['destination']).realpath
+      begin
+        input_directory  = Pathname.new(config['source']).realpath
+      rescue
+        display_error "Can not read source directory, does it exist?"
+      end
 
+      output_directory = Pathname.new(config['destination']).realpath
       doc_assets       = Pathname.new(config['documentation_assets']).realpath unless !File.directory?(config['documentation_assets'])
 
       if doc_assets.nil?
@@ -107,11 +161,11 @@ module Hologram
 
       # if we have an index category defined in our config copy that
       # page to index.html
-      if config['index'] 
+      if config['index']
         if @pages.has_key?(config['index'] + '.html')
           @pages['index.html'] = @pages[config['index'] + '.html']
         else
-          display_warning "Could not generate index.html, there was no content generated for the category #{config['index']}"
+          display_warning "Could not generate index.html, there was no content generated for the category #{config['index']}."
         end
       end
 
@@ -120,18 +174,23 @@ module Hologram
       # Copy over dependencies
       if config['dependencies']
         config['dependencies'].each do |dir|
-          dirpath  = Pathname.new(dir).realpath
-          if File.directory?("#{dir}")
-            `rm -rf #{output_directory}/#{dirpath.basename}`
-            `cp -R #{dirpath} #{output_directory}/#{dirpath.basename}`
+          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
+            display_warning "Could not copy dependency: #{dir}"
           end
         end
       end
 
       if !doc_assets.nil?
         Dir.foreach(doc_assets) do |item|
-         # ignore . and .. directories
-         next if item == '.' or 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
@@ -159,7 +218,7 @@ module Hologram
     def process_files(files, directory)
       files.each do |input_file|
         if input_file.end_with?('md')
-          @pages[File.basename(input_file, '.md') + '.html'] = File.read("#{directory}/#{input_file}")
+          @pages[File.basename(input_file, '.md') + '.html'] = {:md => File.read("#{directory}/#{input_file}"), :blocks => []}
         else
           process_file("#{directory}/#{input_file}")
         end
@@ -170,7 +229,7 @@ module Hologram
     def process_file(file)
       file_str = File.read(file)
       # get any comment blocks that match the patterns:
-      # .sass: //doc (follow by other lines proceeded by a space) 
+      # .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)+)/)
@@ -217,12 +276,16 @@ module Hologram
         end
 
         @doc_blocks[doc_block.name] = doc_block;
-        doc_block.markdown = "\n\n# #{doc_block.title}" + doc_block.markdown
+        doc_block.markdown = "\n\n<h1 id=\"#{doc_block.name}\">#{doc_block.title}</h1>" + doc_block.markdown
       else
         # child file
         parent_doc_block = @doc_blocks[doc_block.parent]
         if parent_doc_block
-          doc_block.markdown = "\n\n## #{doc_block.title}" + doc_block.markdown
+          if doc_block.title.nil?
+            doc_block.markdown = doc_block.markdown
+          else
+            doc_block.markdown = "\n\n<h1 id=\"#{doc_block.name}\">#{doc_block.title}</h1>" + doc_block.markdown
+          end
           parent_doc_block.children[doc_block.name] = doc_block
         else
           @doc_blocks[doc_block.parent] = DocumentBlock.new()
@@ -234,8 +297,13 @@ module Hologram
     def build_pages_from_doc_blocks(doc_blocks, output_file = nil)
       doc_blocks.sort.map do |key, doc_block|
         output_file = doc_block.output_file || output_file
-        @pages[output_file] ||= ""
-        @pages[output_file] << doc_block.markdown
+
+        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
         if doc_block.children
           build_pages_from_doc_blocks(doc_block.children, output_file)
         end
@@ -247,26 +315,45 @@ module Hologram
       # load the markdown renderer we are going to use
       renderer = get_markdown_renderer
 
+      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
+        display_warning "No _header.html found in documentation assets. Without this your css/header will not be included on the generated pages."
+      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
+        display_warning "No _footer.html found in documentation assets. This might be okay to ignore..."
+      end
+
       #generate html from markdown
-      @pages.each do |file_name, markdown|
+      @pages.each do |file_name, page|
         fh = get_fh(output_directory, file_name)
 
+        title = page[:blocks].empty? ? "" : page[:blocks][0][:category]
+
+        tpl_vars = TemplateVariables.new title, file_name, page[:blocks]
+
         # generate doc nav html
-        if File.exists?("#{doc_assets}/header.html")
-          fh.write(File.read("#{doc_assets}/header.html"))
-        else
-          display_warning "No header.html found in documentation assets. Without this your css/header will not be included on the generated pages."
+        unless header_erb.nil?
+          fh.write(header_erb.result(tpl_vars.get_binding))
         end
 
         # write the docs
-        fh.write(renderer.render(markdown))
+        fh.write(renderer.render(page[:md]))
 
         # write the footer
-        if File.exists?("#{doc_assets}/footer.html")
-          fh.write(File.read("#{doc_assets}/footer.html"))
-        else
-          display_warning "No footer.html found in documentation assets. This might be okay to ignore..."
+        unless footer_erb.nil?
+          fh.write(footer_erb.result(tpl_vars.get_binding))
         end
+
         fh.close()
       end
     end
@@ -293,15 +380,15 @@ module Hologram
 
     def validate_config
       unless @config.key?('source')
-        raise "No source directory specified in the config file"
+        display_error "No source directory specified in the config file"
       end
 
       unless @config.key?('destination')
-        raise "No destination directory specified in the config"
+        display_error "No destination directory specified in the config"
       end
 
       unless @config.key?('documentation_assets')
-        raise "No documentation assets directory specified"
+        display_error "No documentation assets directory specified"
       end
     end
 

data/lib/hologram/version.rb

@@ -11,7 +11,7 @@
 #    * Neither the name of the Trulia, Inc. nor the
 #      names of its contributors may be used to endorse or promote products
 #      derived from this software without specific prior written permission.
-# 
+#
 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 # IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 # TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
@@ -25,5 +25,5 @@
 # ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 module Hologram
-  VERSION = "0.5.5"
+  VERSION = "0.5.8"
 end

data/lib/template/doc_assets/_footer.html

@@ -0,0 +1,7 @@
+      </section>
+      <footer>
+        <p>This documentation generated using <a href="http://github.com/trulia/hologram">Hologram</a>
+      </footer>
+    </div>
+  </body>
+</html>

data/lib/template/doc_assets/_header.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html>
+  <head>
+    <title>a brand new styleguide: <%= title %></title>
+    <link rel="stylesheet" href="./your_stylesheet_here.css">
+  </head>
+  <body>
+
+    <nav>
+      <ul>
+      <% for b in blocks %>
+        <li><a href="#<%= b[:name] %>"><%= b[:title] %></a></li>
+      <% end %>
+      </ul>
+    </nav>
+
+    <h1>a brand new style guide, it's super effective</h1>
+    <section class="content">

data/lib/template/hologram_config.yml

@@ -0,0 +1,21 @@
+# The directory containing the source files to parse recursively
+source: ./sass
+
+# The directory that hologram will build to
+destination: ./docs
+
+# The assets needed to build the docs (includes header.html,
+# footer.html, etc)
+# You may put doc related assets here too: images, css, etc.
+documentation_assets: ./doc_assets
+
+# Any other asset folders that need to be copied to the destination
+# folder. Typically this will include the css that you are trying to
+# document. May also include additional folders as needed.
+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.
+index: basics

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hologram
 version: !ruby/object:Gem::Version
-  version: 0.5.5
+  version: 0.5.8
 platform: ruby
 authors:
 - JD Cantrell
@@ -9,76 +9,76 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-02 00:00:00.000000000 Z
+date: 2013-12-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redcarpet
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 2.2.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 2.2.2
 - !ruby/object:Gem::Dependency
   name: sass
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 3.2.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 3.2.7
 - !ruby/object:Gem::Dependency
   name: pygments.rb
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 0.4.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 0.4.2
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: Build doc type things
@@ -89,7 +89,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
+- .gitignore
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -99,6 +99,9 @@ files:
 - lib/hologram.rb
 - lib/hologram/version.rb
 - lib/hologram_markdown_renderer.rb
+- lib/template/doc_assets/_footer.html
+- lib/template/doc_assets/_header.html
+- lib/template/hologram_config.yml
 homepage: http://trulia.github.io/hologram
 licenses:
 - MIT
@@ -109,17 +112,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.0
+rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
 summary: Build document type things.