hologram 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: df438fa1f7fdc30768d2cb9981932488d74ca9ae
-  data.tar.gz: cd01a07f936c9750d9a13146684bc9740a0723fc
+  metadata.gz: ba28330eccb6f989b7d979e73c654ab2d70a34d7
+  data.tar.gz: d754bea437e55dee31fcb283f7957d85e1534b8a
 SHA512:
-  metadata.gz: 57a3a103b3f2af2580d0228c39f1ac74cf82d54e55e8cf6fc7b35b6a185c7d156e14809bdb0cc7111d409322e2179606fd3f0c95ab025d86139412ba5eac844d
-  data.tar.gz: 9dc0380bfce972458b69743ba4002ce376de9c1a335c8c65979203f9714bd93d4505e8b5b6ee635868c490b16a3154df19fbc2c40a3ab40ed42e3a8ddb6734a6
+  metadata.gz: bdaf1aa34dd312b82c9fa26db208fc7106756096b30dc02b9050e0bb69ac2a7e5f68492faabe45466603da074e084f5374386db703ef8c73651b4b817167910a
+  data.tar.gz: 76d55b87389c39f9015d84ad0070b54d953cdcf1a5bda3faeb3ccd780846d155fd4ecc73d8dc3c35e27fa11ef9bae63a07bd1d8a8ee5191a3e95354b74589661

data/.travis.yml

@@ -3,8 +3,8 @@ script: "bundle exec rake spec"
 rvm:
   - 1.9.3
   - 2.0.0
-  - 2.1.0
-  - rbx
+  - 2.1
+  - rbx-2
 
 notifications:
   email: false

data/README.md

@@ -1,13 +1,23 @@
-# Hologram [![Build Status](https://travis-ci.org/trulia/hologram.png)](https://travis-ci.org/trulia/hologram)
+# Hologram
+[![Build Status](https://travis-ci.org/trulia/hologram.png)](https://travis-ci.org/trulia/hologram)
+[![Code Climate](https://codeclimate.com/github/trulia/hologram.png)](https://codeclimate.com/github/trulia/hologram)
 
-Hologram is a Ruby gem that parses comments in your CSS and helps you turn 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.
+1. Documenting your css and javascript, 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.
+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.
+
 
 ## Installation
 
@@ -21,21 +31,29 @@ And then execute:
 
 If you don't use bundler you can run `gem install hologram`.
 
-##Quick Start
 
-```
-hologram init
-```
+## Quick Start
+
+``` hologram init ```
 
-This will create a `hologram_config.yml` file  (more on this below), and also create a starter
-`_header.html` and `_footer.html` file for you. You can then tweak the
-config values and start documenting your css.
+This will create a `hologram_config.yml` file  (more on this below), and
+also create a starter `_header.html` and `_footer.html` file for you.
+You can then tweak the config values and start documenting your css.
 
 Building the documentation is simply:
 
-```
-hologram
-```
+``` hologram ```
+
+
+###Command line flags
+
+Hologram has a couple of command line flags:
+
+* `-c` or `--config` - specify the config file, by default hologram
+  looks for `hologram_config.yml`
+* `-r` or `--root` - specify the directory to use when processing files
+  (useful if you run hologram in a different directory than your assets.
+  Defaults to current working directory)
 
 ## Details
 
@@ -49,74 +67,90 @@ There are two things you need to do to start using hologram:
 ### Creating a YAML config file
 
 Hologram needs a few configuration settings before it can begin to build
-your documentation for you. Once this is set up you can execute hologram by
-simply running:
+your documentation for you. Once this is set up, you can execute hologram
+by simply running:
 
-`hologram path/to/your/config.yml` or (using bundler) `bundle exec hologram path/to/your/config.yml`
+`hologram path/to/your/config.yml` or (using bundler) `bundle exec
+hologram path/to/your/config.yml`
 
 Your config file needs to contain the following key/value pairs
 
 * **source**: relative path to your source files
 
-* **destination**: relative path to where you want the documentation to be
-  built to
+* **destination**: relative path where you want the documentation to be
+  built
 
 * **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
+  the documentation page. This typically includes html fragments
+  (header/footer, etc), style guide 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
+  `_footer.html`. These are used to start and end every html page
   hologram generates.
 
-  Hologram treats `_header.html` and `_footer.html`
-  as ERB files for each page that is generated. You can access the
-  `title`, `file_name`, `blocks`, and `categories`.
-
-  `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`. This is useful for,
-  say, building a menu that lists each component.
+  Hologram treats `_header.html` and `_footer.html` as ERB files for
+  each page that is generated. You can access the `title`, `file_name`,
+  `blocks`, and `categories`.
 
-  `categories` is a list of all the categories found in the documentation
+  `blocks` is a list of each documentation block on the page. Each item
+  in the list has a `title`, `name`, `category`, and optionally a
+  `parent`. This is useful for, say, building a menu that lists each
+  component.
 
-  **Nota Bene:** Filenames that begin with underscores will not be copied into the destination folder.
+  `categories` is a list of all the categories found in the
+  documentation
 
+  **Nota Bene:** 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.
+  additional classes or html tags for different parts of the page.  See
+  `example_markdown_renderer.rb.example` for an example of what your
+  class can look like.
 
-* **index**: (optional) this is a category (see **Documenting your styles** section below) 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 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
+  over into the documentation output directory. ENSURE THE CSS/JS THAT IS
+  ACTUALLY BEING DOCUMENTED IS LISTED HERE. You will also need to ensure
+   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.
+
 
 ##### Example config file
 
-    # The directory containing the source files to parse
-    source: ../components
+    # Hologram will run from same directory where this config file resides
+    # All paths should be relative to there
 
-    # The directory that hologram will build to
-    destination: ../docs
+    # The directory containing the source files to parse recursively
+    source: ./sass
 
-    # The assets needed to build/style the docs (includes header.html, footer.html, etc)
-    documentation_assets: ../hologram_assets
+    # The directory that hologram will build to
+    destination: ./docs
 
-    # A custom markdown renderer that extends `RedCarpet::Render::HTML class`
-    custom_markdown: trulia_markdown_renderer.rb
+    # 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
-    # This is where the CSS/JS you are actually documenting should go
+    # 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
+      - ./build
 
+    # Mark which category should be the index page
+    # Alternatively, you may have an index.md in the documentation assets
+    # folder instead of specifying this config.
+    index: basics
 
-###Documenting your styles
+### Documenting your styles and components
 
-Hologram will scan for stylesheets (.css, .scss, .sass, .less, or .styl) within the **source** directory defined in you configuraiton.
-It will look for comments that match the following:
+Hologram will scan for stylesheets (.css, .scss, .sass, .less, or .styl)
+and javascript source files (.js) within the **source** directory defined
+in your configuration.  It will look for comments that match the following:
 
     /*doc
     ---
@@ -128,10 +162,8 @@ It will look for comments that match the following:
     Button styles can be applied to any element. Typically you'll want
     to use either a `<button>` or an `<a>` element:
 
-    ```html_example
-      <button class="btn btnDefault">Click</button>
-      <a class="btn btnDefault" href="trulia.com">Trulia!</a>
-    ```
+    ```html_example <button class="btn btnDefault">Click</button> <a
+    class="btn btnDefault" href="trulia.com">Trulia!</a> ```
 
     If your button is actually a link to another page, please use the
     `<a>` element, while if your button performs an action, such as
@@ -140,43 +172,73 @@ It will look for comments that match the following:
 
     */
 
-The first section of the comment is a yaml block that defines certain
-aspects of the this documentation block (more on that in the next section). The second part is simply
-markdown as defined by Redcarpet.
+The first section of the comment is a YAML block that defines certain
+aspects of this documentation block (more on that in the next
+section). The second part is simply markdown as defined by Redcarpet.
 
-Notice the use of `html_example`. This tells the markdown renderer that it should treat the example as...well...html. If your project uses [haml](http://haml.info/) you can also use `haml_example`. In that case the output will be html for the example and the code block will show the haml used to generate the html. For components that require [javascript](https://www.destroyallsoftware.com/talks/wat) you can use `js_example` for your javascript. In addition to outputing the javascript in a `<code>` block it will also wrap it in a `<script>` tag for execution.
+Notice the use of `html_example`. This tells the markdown renderer that
+it should treat the example as...well...html. If your project uses
+[haml](http://haml.info/) you can also use `haml_example`. In that case
+the output will be html for the example and the code block will show the
+haml used to generate the html.
 
-####Document YAML section
-The yaml in the documention block can have any key value pair you deem important
-but it specifically looks for the following keys:
+For components that require [javascript](https://www.destroyallsoftware.com/talks/wat)
+you can use `js_example`. In addition to outputting the javascript in a
+`<code>` block it will also wrap it in a `<script>` tag for execution.
 
-* **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.
-* **name**: This is used for grouping components, by assigning
-  a name a component can be referenced in another component as a parent.
-* **parent**: (Optional.) This should be the **name** of another components. If this is set the current component will be displayed as a section within the **parent**'s documentation.
 
-For example, you might have a component with the **name** *buttons* and another component named *buttonSkins*. You could set the **parent** for the *buttonSkins* component to be *buttons*. It would then nest the *buttonSkins* documentation inside the *buttons* documentation.
+#### Document YAML section
 
-Each level of nesting (components are infinitely nestable) will have a heading tag that represents its depth. In the above example *buttons* would have an `<h1>` and *buttonSkins* would have an `<h2>`. This you can [see this exact example in our demo repo](https://github.com/trulia/hologram-example/tree/master/components/button), and the output of this nesting [in our demo styleguide](http://trulia.github.io/hologram-example/base_css.html#Buttons).
+The YAML in the documentation block can have any
+key/value pairs you deem important, but it specifically looks for the
+following keys:
 
-
-###Documentation Assets
+* **title**: The title to display in the documents
+* **category/categories**: This is the broad categories for the component, all
+  components in the same category will be written to the same page. It can be set to either a string or a YAML array. If you use an array, the component will be written to both pages.
+  Note: There is no need to set a category if this component has a **parent**.
+* **name**: This is used for grouping components, by assigning a name, a
+  component can be referenced in another component as a parent. Note that items in
+  the same category are sorted alphabetically by name.
+* **parent**: (Optional.) This should be the **name** of another
+  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**.
+
+For example, you might have a component with the **name** *buttons* and
+another component named *buttonSkins*. You could set the **parent** for
+the *buttonSkins* component to be *buttons*. It would then nest the
+*buttonSkins* documentation inside the *buttons* documentation.
+
+Each level of nesting (components are infinitely nestable) will have a
+heading tag that represents its depth. In the above example *buttons*
+would have an `<h1>` and *buttonSkins* would have an `<h2>`.
+
+You can see [this exact example in our demo
+repo](https://github.com/trulia/hologram-example/tree/master/components/button),
+and the output of this nesting [in our demo
+style guide](http://trulia.github.io/hologram-example/base_css.html#Buttons).
+
+
+### Documentation Assets
 
 The documentation assets folder contains the html, css, js and images
 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.
+Hologram doesn't care too much about what is in here as it is
+intended to be custom for your style guide.
+
 
-#####Styling Your Code Examples
+##### Styling Your Code Examples
+
+Hologram uses [pygments.rb](https://github.com/tmm1/pygments.rb) gem to
+provide syntax highlighting for code examples. One of the assets that
+you probably want to include in your documentation assets folder is a
+css file that styles the "pygmentized" code examples. We use
+`github.css` which can be found along with the css we use to style code
+blocks
+[here](https://github.com/trulia/hologram-example/tree/gh-pages/hologram_assets/doc_assets/css).
 
-Hologram uses [pygments.rb](https://github.com/tmm1/pygments.rb) gem to provide
-syntax highlighting for code examples. One of the assets that you probably want
-to include in your documentation assets folder is a css file that styles the
-"pygmentized" code examples. We use `github.css` which can be found along with the
-css we use to style code blocks [here](https://github.com/trulia/hologram-example/tree/gh-pages/hologram_assets/doc_assets/css).
 
 ## Supported Preprocessors/File Types
 
@@ -188,8 +250,13 @@ The following preprocessors/file types are supported by Hologram:
 - Javascript (.js)
 - Markdown (.md, .markdown)
 
+
 ## Extensions and Plugins
-- [Guard Hologram](https://github.com/kmayer/guard-hologram) is a sweet little gem that uses guard to monitor changes to your hologram project and rebuilds your styleguide on the fly as you make changes.
+
+- [Guard Hologram](https://github.com/kmayer/guard-hologram) is a sweet
+  little gem that uses guard to monitor changes to your hologram project
+  and rebuilds your style guide on the fly as you make changes.
+
 
 ## Contributing
 
@@ -200,7 +267,27 @@ The following preprocessors/file types are supported by Hologram:
 5. Create new Pull Request
 
 
-## License
-[Hologram is licensed under the MIT License](https://github.com/trulia/hologram/blob/master/LICENSE.txt)
+## Authors
+
+Hologram is written and maintained by [August
+Flanagan](http://github.com/aflanagan) and [JD
+Cantrell](http://github.com/jdcantrell).
 
 
+## Contributors
+
+These fine people have also contributed to making hologram a better gem:
+
+* [Rajan Agaskar](https://github.com/ragaskar)
+* Louis Bennett
+* [jho406](https://github.com/jho406)
+* johny (wrote our initial tests!)
+* [Elana Koren](https://github.com/elanakoren)
+* [Ken Mayer](https://github.com/kmayer)
+* [Roberto Ostinelli](https://github.com/ostinelli)
+* [Nicole Sullivan](https://github.com/stubbornella)
+
+
+## License
+
+[Hologram is licensed under the MIT License](https://github.com/trulia/hologram/blob/master/LICENSE.txt)

data/{lib/hologram_markdown_renderer.rb → example_markdown_renderer.rb.example}

@@ -1,4 +1,4 @@
-class HologramMarkdownRenderer < Redcarpet::Render::HTML
+class ExampleMarkdownRenderer < Redcarpet::Render::HTML
   def block_code(code, language)
     if language and language.include?('example')
       if language.include?('js')
@@ -18,12 +18,16 @@ class HologramMarkdownRenderer < Redcarpet::Render::HTML
     case language
       when 'haml_example'
         safe_require('haml', language)
-        return Haml::Engine.new(code.strip).render(Object.new, {})
+        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'

data/hologram.gemspec

@@ -13,9 +13,8 @@ Gem::Specification.new do |spec|
   spec.homepage      = "http://trulia.github.io/hologram"
   spec.license       = "MIT"
 
-  spec.add_dependency "redcarpet", "~> 2.2.2"
-  spec.add_dependency "pygments.rb", "~> 0.4.2"
-  spec.add_dependency "rspec", "~> 2.14.1"
+  spec.add_dependency "redcarpet", "~> 2.2"
+  spec.add_dependency "pygments.rb", "~> 0.4"
 
   spec.files         = `git ls-files`.split($/)
   spec.executables   = ['hologram']
@@ -24,4 +23,5 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 2.14"
 end

data/lib/hologram.rb

@@ -12,8 +12,12 @@ require 'hologram/doc_parser'
 require 'hologram/doc_builder'
 require 'hologram/template_variables'
 require 'hologram/display_message'
+require 'hologram/errors'
+require 'hologram/utils'
+require 'hologram/markdown_renderer'
 
-require 'hologram_markdown_renderer'
+Encoding.default_internal = Encoding::UTF_8
+Encoding.default_external = Encoding::UTF_8
 
 module Hologram
   INIT_TEMPLATE_PATH = File.expand_path('./template/', File.dirname(__FILE__)) + '/'
@@ -22,3 +26,9 @@ module Hologram
     INIT_TEMPLATE_PATH + '/doc_assets',
   ]
 end
+
+class HologramMarkdownRenderer < Hologram::MarkdownRenderer
+  def self.inherited(subclass)
+    puts "HologramMarkdownRenderer is deprecated, please inherit from Hologram::MarkdownRenderer"
+  end
+end

data/lib/hologram/cli.rb

@@ -0,0 +1,45 @@
+require 'optparse'
+
+module Hologram
+  class CLI
+    attr_reader :args
+
+    def initialize(args)
+      @args = args
+    end
+
+    def run
+      return setup if args[0] == 'init'
+
+      #support passing the config file with no command line flag
+      config = args[0].nil? ? 'hologram_config.yml' : args[0]
+
+      OptionParser.new do |opt|
+        opt.on_tail('-h', '--help', 'Show this message.') { puts opt; exit }
+        opt.on_tail('-v', '--version', 'Show version.') { puts "hologram #{Hologram::VERSION}"; exit }
+        opt.on('-c', '--config FILE', 'Path to config file. Default: hologram_config.yml') { |config_file| config = config_file }
+        opt.parse!(args)
+      end
+
+      config.nil? ? build : build(config)
+
+    end
+
+    private
+    def build(config = 'hologram_config.yml')
+      builder = DocBuilder.from_yaml(config)
+      DisplayMessage.error(builder.errors.first) if !builder.is_valid?
+      builder.build
+    rescue CommentLoadError, NoCategoryError => e
+      DisplayMessage.error(e.message)
+    rescue Errno::ENOENT
+      DisplayMessage.error("Could not load config file, try 'hologram init' to get started")
+    end
+
+    def setup
+      DocBuilder.setup_dir
+    rescue => e
+      DisplayMessage.error("#{e}")
+    end
+  end
+end