hologram 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5d23baf9cab5e0651cfa087dd470867770389fb4
-  data.tar.gz: 69b89861f9dbc9a09dc720d9e6a5e1f9ee3b4485
+  metadata.gz: f7506793859da81666c3cfce54518aa60404fd3b
+  data.tar.gz: ebd72609ca0a28fce80ac0384a0c812bb4977c85
 SHA512:
-  metadata.gz: 8eeb3b8e627c7f0dbfc5d4b8b73458ea6da97111979cd734e239e7daa34ba1d4304c6accb1488b4404ba23a1c8f581453d420a48b96f99eaa552583fc265fb32
-  data.tar.gz: 84684a77e6dff76831cb74ec9d0cb33ff299b59593c6f4865dc4d0d960217e9a458466980fdf156ed50810b34179339d98845beb274972855574528fa51f4035
+  metadata.gz: 61dba38e58f9648f72018866b1c82f9569175abef77d2e4159db83adaf1bff1d093450096ea5215ab1df555d570fed4779ab4c319736bac218f6988cd8989361
+  data.tar.gz: aaea89e65dd705d79a57885a941d969eb4d278e81afc2e4a7be281a393d023fa86b66316b36bac96c3b33504b0230dcbd3b772d5323495111b35545cdbdecec8

data/.travis.yml

@@ -4,7 +4,6 @@ rvm:
   - 1.9.3
   - 2.0.0
   - 2.1
-  - rbx-2
 
 notifications:
   email: false

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 #Changelog
 
+##1.3.0 - 2015-01-15
+
+Spencer Hurst, Beatrice Peng, and Geoff Pleiss
+* Overhaul the code examples code to allow easier customization
+
+Nicole Sullivan and Geoff Pleiss
+* Add class styleguide to generated markdown documentation
+* Add nav_level config and section navigation
+* Tabular code examples (ie html_example_table, haml_example_table, etc)
+
+Paul Meskers and Nicole Sullivan
+* Add code example support for JSX
+
+Geoff Pleiss
+* Add config to exit on warnings
+* Add internal reference links for linking to other sections within
+  hologram's generated documentation
+
+Jonathan Dexter
+* Fix document comment block regex to work with CR
+
+Beatrice Peng
+* Warn when multiple components have the same name
+
+Chris Holmes
+* Documentation updates
+
+Antoine - a5e
+* Escape title in documentation block
+
+JD Cantrell
+* Try .sass style comments when a .scss file has no doc blocks
+* Remove all backtick commands with FileUtils call (better support on
+  non-linux/osx machines)
+* Add code example support for slim
+
+
 ##1.2.0 - 2014-07-22
 
 JD Cantrell

data/README.md

@@ -1,6 +1,8 @@
 # Hologram
+[![Gem Version](https://badge.fury.io/rb/hologram.png)](https://rubygems.org/gems/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)
+[![Dependency Status](https://gemnasium.com/trulia/hologram.png)](https://gemnasium.com/trulia/hologram)
 
 Hologram is a Ruby gem that parses comments in your CSS and helps you
 turn them into a beautiful style guide.
@@ -36,8 +38,9 @@ If you don't use bundler you can run `gem install hologram`.
 
 ``` 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.
+This will create a `hologram_config.yml` file  (more on this below),
+starter `_header.html` and `_footer.html` files,
+and starter templates for rendering code examples.
 You can then tweak the config values and start documenting your css.
 
 Add some documentation to one of your stylesheets:
@@ -113,10 +116,41 @@ Your config file needs to contain the following key/value pairs
   **Nota Bene:** Filenames that begin with underscores will not be
   copied into the destination folder.
 
+* **code\_example\_templates**: (optional) Hologram uses the files in this folder to
+  format the code examples in the styleguide. The initializer generates 4 files:
+
+  * `markup_example_template.html.erb` - used for html, haml and slim examples
+
+  * `markup_table_template.html.erb` - used for multiple html, haml and slim
+  examples layed out in a table (see
+  [the tabular layout docs](#tabular-layout-for-component-documentation)
+  for more information)
+
+  * `js_example_template.html.erb` - used for js examples
+
+  * `jsx_example_template.html.erb` - used for jsx examples
+
+  The html in the files will be rendered for every code example in the
+  styleguide. The variable `rendered_example` represents the html
+  generated by the example, while the variable `code_example` represents the
+  formatted and escaped code behind the example.
+
+  See [the documentation on custom code renderers](#custom_code_example_renderers)
+  for more information,
+
+  **Nota Bene:** If template files are missing, or this folder does not exist,
+  hologram will use default templates.
+
+* **code\_example\_renderers**: (optional) A folder that contains your custom
+  code renderers. For example, if you want to have `coffee_example`s in your
+  code, write a coffeescript renderer and place it in this folder. See
+  [#custom_code_example_renders](below) for more inforamtion on this.
+
 * **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.  See
-  `example_markdown_renderer.rb.example` for an example of what your
+  [example_markdown_renderer.rb.example]
+  (example_markdown_renderer.rb.example) for an example of what your
   class can look like.
 
 * **index**: (optional) this is a category (see **Documenting your
@@ -129,6 +163,16 @@ 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.
 
+* **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`.
+
+* **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)
+  If you want Hologram to exit on these warnings, set the value to 'true'
+  (Default value is 'false')
 
 ##### Example config file
 
@@ -151,6 +195,17 @@ Your config file needs to contain the following key/value pairs
     # You may put doc related assets here too: images, css, etc.
     documentation_assets: ./doc_assets
 
+    # The folder that contains templates for rendering code examples.
+    # If you want to change the way code examples appear in the styleguide,
+    # modify the files in this folder
+    code_example_templates: ./code_example_templates
+
+    # The folder that contains custom code example renderers.
+    # If you want to create additional renderers that are not provided
+    # by Hologram (i.e. coffeescript renderer, jade renderer, etc)
+    # place them in this folder
+    code_example_renderers: ./code_example_renderers
+
     # 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.
@@ -162,6 +217,17 @@ Your config file needs to contain the following key/value pairs
     # folder instead of specifying this config.
     index: basics
 
+    # To output navigation for top level sections, set the value to
+    # 'section'. To output navigation for sub-sections, set the value to `all`
+    nav_level: all
+
+    # 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)
+    # If you want Hologram to exit on these warnings, set the value to 'true'
+    # (Default value is 'false')
+    exit_on_warnings: false
+
 ### Documenting your styles and components
 
 Hologram will scan for stylesheets (.css, .scss, .sass, .less, or .styl)
@@ -204,6 +270,55 @@ For components that require [javascript](https://www.destroyallsoftware.com/talk
 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.
 
+Additionally, html elements that are generated via markdown will have a
+class `styleguide` appended to them. You can use this to apply css to
+the styleguide itself.
+
+#### Tabular layout for component documentation
+
+If you want the code snippet next to the rendered component, instead of below,
+render your component horizontally by applying the `html_example_table` or
+`haml_example_table` modifiers to the code block.
+
+    /*doc
+    ---
+    title: Buttons
+    name: button
+    category: Base CSS
+    ---
+
+    ```html_example_table
+    <button class="btn btnDefault">Click</button>
+
+    <a class="btn btnDefault" href="trulia.com">Trulia!</a>
+    ```
+
+    */
+
+**NB:** Components separated by a blank line will be rendered as separate table rows.
+
+#### Referencing other components
+
+For some components, you may want to reference the documentation of another component.
+As an example, you may want your link components to link to the button documentation.
+
+    /*doc
+    ---
+    title: Links
+    name: links
+    category: Other Category
+    ---
+
+  ...
+
+    You may want to use a button for a link.
+    See [the button documentation][button] for more info.
+
+    */
+
+You can use a reference link of the form `[link description][component_name]`
+to link to any other component in the styleguide.
+These links will even work if the referenced component belongs to a different category.
 
 #### Document YAML section
 
@@ -257,10 +372,132 @@ css file that styles the "pygmentized" code examples. We use
 blocks
 [here](https://github.com/trulia/hologram-example/tree/gh-pages/hologram_assets/doc_assets/css).
 
+### Custom Code Example Renderers
+
+By default, hologram supports the following code example types:
+
+- `html_example` and `html_example_table`
+- `haml_example` and `haml_example_table`
+- `slim_example` and `slim_example_table`
+- `js_example`
+- `jsx_example`
+
+Let's say you want to include coffeescript examples in your styleguide.
+You'll need to create a custom renderer for this.
+
+First, if none of the included templates (`markup_example_template`, `js_example_template`, etc)
+work for you, create new custom template files. In this example,
+let's say you have
+the templates `my_custom_coffee_example_template.html.erb` and
+`my_custom_coffee_table_template.html.erb` in your `./code_example_templates` folder.
+
+```erb
+<!-- ./code_example_templates/my_custom_coffee_example_template.html.erb -->
+
+<script><%= rendered_example %></script>
+<div class="codeBlock coffeeExample">
+  <div class="highlight">
+    <pre><%= code_example %></pre>
+  </div>
+</div>
+```
+
+```erb
+<!-- ./code_example_templates/my_custom_coffee_table_template.html.erb -->
+
+<div class="codeTable">
+  <table>
+    <tbody>
+      <% examples.each do |example| %>
+        <tr>
+          <td>
+            <script><%= example.rendered_example %></script>
+            <div class="codeBlock coffeeExample">
+              <div class="highlight">
+                <pre><%= example.code_example %></pre>
+              </div>
+            </div>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>
+```
+
+Next, create a custom renderer for coffeescript in the file
+`./code_example_renderers/coffee_renderer.rb`.
+
+```ruby
+# ./code_example_renderers/coffee_renderer.rb
+
+require 'coffee-script'
+
+Hologram::CodeExampleRenderer::Factory.define('coffee') do
+  example_template 'my_custom_coffee_example_template'
+  table_template 'my_custom_coffee_table_template'
+
+  lexer { Rouge::Lexer.find(:coffee) }
+
+  rendered_example do |code|
+    CoffeeScript.compile(code)
+  end
+end
+```
+
+Now you should be able to render coffeescript examples in your styleguide.
+You can render single coffeescript examples...
+
+  ```coffee_example
+  $('#myDiv').click ->
+    alert 'Oh wow we are rendering coffee script'
+  ```
+
+Or you can render coffeescript tables...
+
+  ```coffee_example_table
+  $('#myDiv').click ->
+    alert 'Oh wow we are rendering coffee script'
+
+  $('#myOtherDiv').click ->
+    console.log 'Yeah coffee script!'
+
+  $('#yetAnotherDiv').click ->
+    window.location =
+  ```
+
+Here's some details on the code example renderer factory:
+
+* `Hologram::CodeExampleRenderer::Factory.define(example_type, &block)` -
+  this is how you declare a custom renderer. `example_type` is the name of the
+  renderer, and determines the example name. For example, if `example_type`
+  was "foobar", in your styleguide you can create `foobar_example`s and
+  `foobar_example_table`s
+
+* `example_template` - the name of the template used to render the example,
+  minus the `.html.erb` extension (e.g. "markup_example_template"). It
+  should live in your **code\_example\_templates** folder
+
+* `table_template` - (optional) the name of the template used to render examples in
+  tabular form, minus the extension (e.g. "markup_table_template").
+
+* `lexer` - (optional) a Rogue Lexer that matches the syntax of your
+  example (i.e. `Rouge::Lexer.find(:haml)`, `Rouge::Lexer.find(:ruby)`).
+  Here's a [complete list of possible lexers](http://rouge.jayferd.us/demo).
+  If this argument is not provided, hologram will guess what the best
+  one is.
+
+* `rendered_example` - (optional) this is the set of instructions to
+  "translate" your exaple so it can be rendered. I.e. for coffeescript
+  to be "rendered" in the browser, you need to transform it to
+  javascript (as can be seen in the block above).
+  For haml, you need to transform it to html.
+  If no block is provided, the code is rendered as is.
 
 ## Supported Preprocessors/File Types
 
 The following preprocessors/file types are supported by Hologram:
+
 - Sass (.scss, .sass)
 - Less (.less)
 - Stylus (.styl)
@@ -276,10 +513,11 @@ The following preprocessors/file types are supported by Hologram:
   and rebuilds your style guide on the fly as you make changes.
 - [Grunt Hologram](https://github.com/jchild3rs/grunt-hologram/) is a sweet
   little grunt task that will generate your hologram style guide.
+- [Hologram Plugin for Gulp](https://gist.github.com/jchild3rs/470be49a4bc4caf3ca8a) is a gulp task for hologram.
 - [Classname Clicker](https://github.com/bigethan/hologram-addons/) is a handy
-  UI addition that gives the ability to see rules that apply to a classname by 
+  UI addition that gives the ability to see rules that apply to a classname by
   clicking on them within hologram.
-- [Cortana](https://github.com/Yago/Cortana) is a theme for hologram. It also 
+- [Cortana](https://github.com/Yago/Cortana) is a theme for hologram. It also
   includes a handy search feature.
 
 ## Contributing

data/hologram.gemspec

@@ -24,4 +24,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", "~> 2.14"
+  spec.add_development_dependency "haml"
+  spec.add_development_dependency "slim"
 end

data/lib/hologram.rb

@@ -17,6 +17,7 @@ require 'hologram/display_message'
 require 'hologram/errors'
 require 'hologram/utils'
 require 'hologram/markdown_renderer'
+require 'hologram/code_example_renderer'
 
 Encoding.default_internal = Encoding::UTF_8
 Encoding.default_external = Encoding::UTF_8
@@ -26,6 +27,7 @@ module Hologram
   INIT_TEMPLATE_FILES = [
     INIT_TEMPLATE_PATH + '/hologram_config.yml',
     INIT_TEMPLATE_PATH + '/doc_assets',
+    INIT_TEMPLATE_PATH + '/code_example_templates',
   ]
 end
 

data/lib/hologram/block_code_renderer.rb

@@ -0,0 +1,45 @@
+require 'erb'
+
+module Hologram
+  class BlockCodeRenderer
+    def initialize(code, markdown_language)
+      @code = code
+      @markdown_language = markdown_language
+    end
+
+    def render
+      if is_table? && table_template
+        examples = code.split("\n\n").map { |code_snippet| example_class.new(code_snippet) }
+        ERB.new(table_template).result(binding)
+      else
+        example = example_class.new(code)
+        ERB.new(example_template).result(example.get_binding)
+      end
+    end
+
+    private
+
+    attr_reader :code, :markdown_language
+
+    def example_class
+      CodeExampleRenderer.example_class_for(example_type)
+    end
+
+    def example_template
+      CodeExampleRenderer.example_template_for(example_type)
+    end
+
+    def table_template
+      CodeExampleRenderer.table_template_for(example_type)
+    end
+
+    def example_type
+      match = /(\w+)_example/.match(markdown_language)
+      match ? match.captures.first : nil
+    end
+
+    def is_table?
+      markdown_language && markdown_language.include?('example_table')
+    end
+  end
+end