hologram 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b0342d18f4b8efdeb45281ae626fd406eb957ec7
-  data.tar.gz: c75e2c8bc874ab6933fc1e91075c837912f8f2f9
+  metadata.gz: 3bbee4bb5cc8c9c22b1e102dd0dfb5d4e0bf3399
+  data.tar.gz: 9d179e3adbc3e2845b06f584ad50565aa41c8583
 SHA512:
-  metadata.gz: 0cdd1efba7738ae5129030f0ce399cd57a621a199a6faf65e31dca37c4573d775eb1a12fe178e7476fffa76e84d7fc30a8869092011ca3a3cadf5e35fc360b58
-  data.tar.gz: 353cd7f8fc431ab2f3520a30b566df28cd6f6557025e240685d5e5bc1c389bdc2941d0b36e753e0054c1c40ffc98bbdc48f73beeba1e7d05fa04b00ea8afe667
+  metadata.gz: fd7de23120bde386cd1d1de46d11f72df1a165af983d61217ac2f06ef0ecc6f4bf8d833c6c61a8da26f636f71353d4dea3354e7297fe8fed345acecca1258613
+  data.tar.gz: f38eb0c5d036d72e16acac3705378de8de014e6dbed86f7813fe8833b4159a964adf63161cc158396b0316d7cb17a4cad8690477844e22d108dd5b092a6969f6

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 #Changelog
 
+##1.4.0 - 2015-03-29
+
+New Features:
+
+Joe Bartlett
+* Allow markdown files to contain hologram yaml
+
+Anthony Chen
+* Add config option for allowing additional file extensions to be
+  processed
+
+JD Cantrell
+* Add config option to ignore specific paths and files.
+
+Bug fixes:
+
+Noppanit Charassinvichai and Ryan Mathews
+* Correctly copy assets
+
+JD Cantrell
+* Use correct title for index category pages
+* Make scss regex behave like sass regex
+* Template variables for erb files no longer vary based on when the erb
+  is processed.
+
+
 ##1.3.0 - 2015-01-15
 
 Spencer Hurst, Beatrice Peng, and Geoff Pleiss

data/README.md

@@ -163,11 +163,20 @@ Your config file needs to contain the following key/value pairs
    that they are included on your pages. A simple way to do this is to add
    `<link>` and `<script src=>` tags to the `_header.html` file.
 
+* **ignore_paths**: (optional) a **list** of paths to ignore. This can be a file
+  name or a glob. Be sure to wrap globs in double quotes to keep yaml
+  from getting too upset (ie good:"*.erb" vs bad:*.erb).
+
 * **nav_level**: (optional) Sets the level of section navigation desired.
   `section` sets it to show sub navigation in top level sections.
   `all` sets it to show sub navigation for all sections. `all` can be a bit
   much, you'll probably want `section`.
 
+* **custom_extensions**: (optional) Additional file extensions that will be
+  included in the parse. Accepts both a single value and an array. The
+  current supported file extensions are `.css`, `.scss`, `.less`, `.sass`,
+  `.styl`, `.js`, `.md`, `.markdown` and `.erb`.
+
 * **exit_on_warnings**: (optional) Hologram displays warnings when there
   are issues with your docs (e.g. if a component's parent is not found,
   if the _header.html and/or _footer.html files aren't found)
@@ -213,7 +222,7 @@ Your config file needs to contain the following key/value pairs
       - ./build
 
     # Mark which category should be the index page
-    # Alternatively, you may have an index.md in the documentation assets
+    # Alternatively, you may have an index.md in the source directory root
     # folder instead of specifying this config.
     index: basics
 
@@ -337,6 +346,10 @@ following keys:
   component. If this is set, the current component will be displayed as
   a section within the **parent**'s documentation, but only if it specifies
   the same **category**, or allows the **category** to be inherited from its **parent**.
+* **hologram**: (markdown only) To avoid conflicts with Jekyll and
+  other YAML+markdown formats, Markdown (`.md`) files must include a
+  `hologram: true` key/value pair in the YAML block to indicate that
+  it is intended to be processed by Hologram.
 
 For example, you might have a component with the **name** *buttons* and
 another component named *buttonSkins*. You could set the **parent** for

data/lib/hologram/doc_builder.rb

@@ -63,6 +63,8 @@ module Hologram
       @exit_on_warnings = options['exit_on_warnings']
       @code_example_templates = options['code_example_templates']
       @code_example_renderers = options['code_example_renderers']
+      @custom_extensions = Array(options['custom_extensions'])
+      @ignore_paths = options.fetch('ignore_paths', [])
 
       if @exit_on_warnings
         DisplayMessage.exit_on_warnings!
@@ -132,7 +134,9 @@ module Hologram
     end
 
     def build_docs
-      doc_parser = DocParser.new(input_dir, index, @plugins, nav_level: @nav_level)
+      doc_parser = DocParser.new(input_dir, index, @plugins, nav_level: @nav_level,
+                                                             custom_extensions: @custom_extensions,
+                                                             ignore_paths: @ignore_paths)
       @pages, @categories = doc_parser.parse
 
       if index && !@pages.has_key?(index + '.html')
@@ -151,7 +155,8 @@ module Hologram
         # ignore . and .. directories and files that start with
         # underscore
         next if item == '.' or item == '..' or item.start_with?('_')
-        FileUtils.rm "#{output_dir}/#{item}", :force => true
+        FileUtils.rm "#{output_dir}/#{item}", :force => true if File.file?("#{output_dir}/#{item}")
+        FileUtils.rm_rf "#{output_dir}/#{item}" if File.directory?("#{output_dir}/#{item}")
         FileUtils.cp_r "#{doc_assets_dir}/#{item}", "#{output_dir}/#{item}"
       end
     end

data/lib/hologram/doc_parser.rb

@@ -1,6 +1,6 @@
 module Hologram
   class DocParser
-    SUPPORTED_EXTENSIONS = ['.css', '.scss', '.less', '.sass', '.styl', '.js', '.md', '.markdown', '.erb' ]
+    DEFAULT_SUPPORTED_EXTENSIONS = ['.css', '.scss', '.less', '.sass', '.styl', '.js', '.md', '.markdown', '.erb' ]
     attr_accessor :source_path, :pages, :doc_blocks, :nav_level
 
     def initialize(source_path, index_name = nil, plugins=[], opts={})
@@ -10,6 +10,9 @@ module Hologram
       @nav_level = opts[:nav_level] || 'page'
       @pages = {}
       @output_files_by_category = {}
+      @supported_extensions = DEFAULT_SUPPORTED_EXTENSIONS
+      @supported_extensions += opts[:custom_extensions] if opts[:custom_extensions]
+      @ignore_paths = opts[:ignore_paths] || []
     end
 
     def parse
@@ -44,6 +47,8 @@ module Hologram
         name = @index_name + '.html'
         if @pages.has_key?(name)
           @pages['index.html'] = @pages[name]
+          title, _ = @output_files_by_category.rassoc(name)
+          @output_files_by_category[title] = 'index.html'
         end
       end
 
@@ -69,9 +74,18 @@ module Hologram
     end
 
     def process_files(files, directory, doc_block_collection)
-      files.each do |input_file|
+
+      if !@ignore_paths.empty?
+        valid_files = files.select { |input_file|
+          @ignore_paths.select { |glob| File.fnmatch(glob, input_file) }.empty?
+        }
+      else
+        valid_files = files
+      end
+
+      valid_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 => []}
+          process_markdown_file("#{directory}/#{input_file}", doc_block_collection)
         elsif input_file.end_with?('erb')
           @pages[File.basename(input_file, '.erb')] = {:erb => File.read("#{directory}/#{input_file}")}
         else
@@ -80,6 +94,16 @@ module Hologram
       end
     end
 
+    def process_markdown_file(file, doc_block_collection)
+      file_str = File.read(file)
+
+      if file_str.match(/^-{3}\n.*hologram:\s*true.*-{3}/m)
+        doc_block_collection.add_doc_block(file_str, file)
+      else
+        @pages[File.basename(file, '.md') + '.html'] = {:md => file_str, :blocks => []}
+      end
+    end
+
     def process_file(file, doc_block_collection)
       file_str = File.read(file)
       # get any comment blocks that match the patterns:
@@ -90,7 +114,7 @@ module Hologram
         #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)
+        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')
@@ -129,7 +153,7 @@ module Hologram
     end
 
     def is_supported_file_type?(file)
-      SUPPORTED_EXTENSIONS.include?(File.extname(file)) and !Dir.exists?(file)
+      @supported_extensions.include?(File.extname(file)) and !Dir.exists?(file)
     end
 
     def get_file_name(str)

data/lib/hologram/template_variables.rb

@@ -10,7 +10,7 @@ module Hologram
 
     def set_args(args)
       args.each do |k,v|
-        instance_variable_set("@#{k}", v) unless v.nil?
+        instance_variable_set("@#{k}", v)
       end
     end
 

data/lib/hologram/version.rb

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

data/spec/doc_builder_spec.rb

@@ -252,6 +252,8 @@ describe Hologram::DocBuilder do
       builder.build
       expect(File.read(File.expand_path('../fixtures/styleguide/base_css.html', __FILE__))).to eq File.read(File.join(builder.destination, '.', 'base_css.html'))
       expect(File.read(File.expand_path('../fixtures/styleguide/index.html', __FILE__))).to eq File.read(File.join(builder.destination, '.', 'index.html'))
+      expect(File.read(File.expand_path('../fixtures/styleguide/code.html', __FILE__))).to eq File.read(File.join(builder.destination, '.', 'code.html'))
+      expect(File.read(File.expand_path('../fixtures/styleguide/jekyll.html', __FILE__))).to eq File.read(File.join(builder.destination, '.', 'jekyll.html'))
     end
   end
 end

data/spec/doc_parser_spec.rb

@@ -120,7 +120,7 @@ multi-parent
       end
 
       it 'adds two categories to output_files_by_category' do
-        expect(output_files_by_category).to eql({'Foo'=>'foo.html', 'Base CSS'=>'base_css.html', 'Bar'=>'bar.html'})
+        expect(output_files_by_category).to eql({'Foo'=>'foo.html', 'Base CSS'=>'base_css.html', 'Bar'=>'bar.html', 'Code'=>'code.html'})
       end
     end
 

data/spec/fixtures/source/components/bem.md

@@ -0,0 +1,12 @@
+---
+hologram: true
+title: BEM-like class naming
+name: bem
+category: Code
+---
+
+We use a BEM-like naming convention [similar to Harry Roberts'](http://cssguidelin.es/#bem-like-naming):
+
+    .block {}
+    .block__element {}
+    .block--modifier {}

data/spec/fixtures/source/components/jekyll.md

@@ -0,0 +1,7 @@
+---
+layout: post
+title: Blogging Like a Hacker
+---
+
+This is an example of a markdown file whose YAML frontmatter will
+be ignored by Hologram.

data/spec/fixtures/styleguide/code.html

@@ -0,0 +1,73 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width">
+
+    <title>My Style Guide Code</title>
+
+    <!-- Styleguide CSS -->
+    <link rel="stylesheet" href="static/css/doc.css">
+    <link rel="stylesheet" href="static/css/github.css">
+
+    <!-- CSS to be documented -->
+    <link rel="stylesheet" href="extra/css/screen.css">
+</head>
+
+  <body>
+    <header class="header pbn" role="banner">
+      <div class="backgroundHighlight typeReversed1">
+        <div class="container">
+          <h1 class="h2 mvs">My Style Guide</h1>
+        </div>
+      </div>
+      <div class="backgroundLowlight typeReversed1">
+        <div class="container">
+          <span>
+            <ul class="docNav listInline">
+              <!-- Add you pages here -->
+              <li><a href="index.html">Intro</a></li>
+              <li><a href="base_css.html">Base CSS</a></li>
+            </ul>
+          </span>
+        </div>
+      </div>
+      <!-- //header/container -->
+    </header>
+
+    <div class="content">
+      <section>
+        <div class="line">
+
+          <div class="col cols4">
+            <div class="componentMenu box boxBasic backgroundBasic">
+              <div class="boxBody pan">
+                <ul class="componentList listBorderedHover">
+                  
+                    <li><a href="#bem">BEM-like class naming</a></li>
+                  
+                </ul>
+              </div>
+            </div>
+          </div>
+
+          <div class="main col cols20 lastCol">
+
+
+
+<h1 id="bem" class="styleguide">BEM-like class naming</h1>
+<p class="styleguide">We use a BEM-like naming convention <a class="styleguide" href="http://cssguidelin.es/#bem-like-naming" title="http://cssguidelin.es/#bem-like-naming">similar to Harry Roberts&#39;</a>:</p><div class="codeBlock">
+  <div class="highlight">
+    <pre>.block {}
+.block__element {}
+.block--modifier {}</pre>
+  </div>
+</div>      </div>
+    </div>
+  </section>
+  <footer>
+    The source code for this style guide is licensed under the MIT license.
+  </footer>
+</div>
+</body>
+</html>

data/spec/fixtures/styleguide/jekyll.html

@@ -0,0 +1,68 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width">
+
+    <title>My Style Guide </title>
+
+    <!-- Styleguide CSS -->
+    <link rel="stylesheet" href="static/css/doc.css">
+    <link rel="stylesheet" href="static/css/github.css">
+
+    <!-- CSS to be documented -->
+    <link rel="stylesheet" href="extra/css/screen.css">
+</head>
+
+  <body>
+    <header class="header pbn" role="banner">
+      <div class="backgroundHighlight typeReversed1">
+        <div class="container">
+          <h1 class="h2 mvs">My Style Guide</h1>
+        </div>
+      </div>
+      <div class="backgroundLowlight typeReversed1">
+        <div class="container">
+          <span>
+            <ul class="docNav listInline">
+              <!-- Add you pages here -->
+              <li><a href="index.html">Intro</a></li>
+              <li><a href="base_css.html">Base CSS</a></li>
+            </ul>
+          </span>
+        </div>
+      </div>
+      <!-- //header/container -->
+    </header>
+
+    <div class="content">
+      <section>
+        <div class="line">
+
+          <div class="col cols4">
+            <div class="componentMenu box boxBasic backgroundBasic">
+              <div class="boxBody pan">
+                <ul class="componentList listBorderedHover">
+                  
+                </ul>
+              </div>
+            </div>
+          </div>
+
+          <div class="main col cols20 lastCol">
+
+
+
+<hr>
+<p class="styleguide">layout: post</p>
+<h2>title: Blogging Like a Hacker</h2>
+<p class="styleguide">This is an example of a markdown file whose YAML frontmatter will
+be ignored by Hologram.</p>      </div>
+    </div>
+  </section>
+  <footer>
+    The source code for this style guide is licensed under the MIT license.
+  </footer>
+</div>
+</body>
+</html>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hologram
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
 - JD Cantrell
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-05 00:00:00.000000000 Z
+date: 2015-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redcarpet
@@ -180,9 +180,11 @@ files:
 - spec/fixtures/renderer/valid_renderer.rb
 - spec/fixtures/source/colors/colors.css
 - spec/fixtures/source/components/background/backgrounds.css
+- spec/fixtures/source/components/bem.md
 - spec/fixtures/source/components/button/buttons.css
 - spec/fixtures/source/components/button/skin/buttonSkins.css
 - spec/fixtures/source/components/index.md
+- spec/fixtures/source/components/jekyll.md
 - spec/fixtures/source/config.yml
 - spec/fixtures/source/config_multi_source.yml
 - spec/fixtures/source/extra/css/screen.css
@@ -190,8 +192,10 @@ files:
 - spec/fixtures/source/templates/_header.html
 - spec/fixtures/source/templates/static/css/doc.css
 - spec/fixtures/styleguide/base_css.html
+- spec/fixtures/styleguide/code.html
 - spec/fixtures/styleguide/extra/css/screen.css
 - spec/fixtures/styleguide/index.html
+- spec/fixtures/styleguide/jekyll.html
 - spec/fixtures/styleguide/static/css/doc.css
 - spec/hologram_markdown_renderer_spec.rb
 - spec/link_helper_spec.rb
@@ -218,7 +222,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Build document type things.
@@ -237,9 +241,11 @@ test_files:
 - spec/fixtures/renderer/valid_renderer.rb
 - spec/fixtures/source/colors/colors.css
 - spec/fixtures/source/components/background/backgrounds.css
+- spec/fixtures/source/components/bem.md
 - spec/fixtures/source/components/button/buttons.css
 - spec/fixtures/source/components/button/skin/buttonSkins.css
 - spec/fixtures/source/components/index.md
+- spec/fixtures/source/components/jekyll.md
 - spec/fixtures/source/config.yml
 - spec/fixtures/source/config_multi_source.yml
 - spec/fixtures/source/extra/css/screen.css
@@ -247,8 +253,10 @@ test_files:
 - spec/fixtures/source/templates/_header.html
 - spec/fixtures/source/templates/static/css/doc.css
 - spec/fixtures/styleguide/base_css.html
+- spec/fixtures/styleguide/code.html
 - spec/fixtures/styleguide/extra/css/screen.css
 - spec/fixtures/styleguide/index.html
+- spec/fixtures/styleguide/jekyll.html
 - spec/fixtures/styleguide/static/css/doc.css
 - spec/hologram_markdown_renderer_spec.rb
 - spec/link_helper_spec.rb