style-guide 0.6.0 → 0.6.1

data/README.md

@@ -1,31 +1,84 @@
-# StyleGuide
+# Style Guide
 
 [![Build Status](https://secure.travis-ci.org/pivotalexperimental/style-guide.png?branch=master)](https://travis-ci.org/pivotalexperimental/style-guide) [![Dependency Status](https://gemnasium.com/pivotalexperimental/style-guide.png)](https://gemnasium.com/pivotalexperimental/style-guide) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/pivotalexperimental/style-guide)
 
-Quickly see the styled output of your application.
+Style Guide was born out of a need to quickly audit the CSS applied to
+visual elements and iterate on them in a controlled environment.  It is
+implemented as a Rails engine in order to stay close to the application being
+styled.
 
-## Example
+When used with [guard-livereload](https://github.com/guard/guard-livereload),
+Style Guide automatically reloads itself when you make changes to the CSS,
+Javascript or HTML in your site.
 
-The canonical deployed instance is located at [http://swivel.herokuapp.com](http://swivel.herokuapp.com)
 
 ## Usage
 
-First, require the StyleGuide gem in your application.rb file:
+First, require the StyleGuide gem in `application.rb`:
 
-    Bundler.require
     require "style_guide"
 
-Next, mount the StyleGuide application in your `routes.rb` file:
-
-    mount StyleGuide::Engine => "/style-guide"
 
-By default, StyleGuide will attempt to load directories full of partials and render them at its mounted path.  Here's how to add your own directory full of partials:
+Then, append a directory of partials in `application.rb`:
 
     config.style_guide.partial_paths << Rails.root.join("app/views/styles")
 
-You could, however, just display only your partials (note the assignment):
 
-    config.style_guide.partial_paths = [Rails.root.join("app/views/styles")]
+Next, mount the StyleGuide application in `routes.rb`:
+
+    mount StyleGuide::Engine => "/style-guide" unless Rails.env.production?
+
+
+Finally, add `Rack::LiveReload` to `environments/development.rb`:
+
+    config.middleware.insert_before(::Rack::Lock, ::Rack::LiveReload)
+
+
+## Enhancing Your Experience
+
+Running [Guard](https://github.com/guard/guard) is highly recommended:
+
+    $ guard init
+    INFO - livereload guard added to Guardfile, feel free to edit it
+    $ guard
+    INFO - LiveReload is waiting for a browser to connect.
+
+Using [Foreman](https://github.com/ddollar/foreman) to manage the startup of
+both your Rails app and Guard is an excellent idea.
+
+First, turn off the Guard interactor so that it doesn't try to block output.
+Add this line to the top of your `Guardfile`:
+
+    interactor :off
+
+Then add the following lines to `Procfile`, located in the root of your app:
+
+    web: bundle exec rails s
+    guard: bundle exec guard
+
+
+## Best Practices
+
+* Do not attempt to do layout in the Style Guide.  Attempting to make it lay
+  out your pages will lead you down the road of madness.
+
+* The canonical installation of Style Guide pulls in all of the
+  directories under `app/views/style_guide`, like so:
+
+      config.style_guide.partial_paths << Rails.root.join("app/views/style_guide/*")
+
+* From here, the Style Guide is broken down into sections,
+  like "Buttons", "Forms" and "Typography".
+
+* You should only use static content in the partials you render
+  to the Style Guide.
+
+
+## Example
+
+You can see an example of Style Guide at swivel's automatically-deployed
+testing instance: [http://swivel.herokuapp.com](http://swivel.herokuapp.com)
+
 
 ## License
 

data/config/locales/en.yml

@@ -2,15 +2,15 @@ en:
   style_guide:
     buttons:
       disabled_anchor: >
-        Make <code>&lt;a&gt;</code> buttons look unclickable by adding
-        the <code>.disabled</code> class
+        Make `<a>` buttons look unclickable by adding
+        the `.disabled` class
       disabled_element: >
-        Make <code>&lt;button&gt;</code> buttons look unclickable by adding
-        the <code>.disabled</code> class
+        Make `<button>` buttons look unclickable by adding
+        the `.disabled` class
       sizes: >
         Fancy larger or smaller buttons?
-        Add <code>.btn-large</code>, <code>.btn-small</code>, or
-        <code>.btn-mini</code> for additional sizes.
+        Add `.btn-large`, `.btn-small`, or
+        `.btn-mini` for additional sizes.
       types: >
         Need different buttons for different occasions?  Add some class!
 
@@ -19,42 +19,40 @@ en:
       controls_checkbox_and_radio: >
         Checkboxes are for selecting one or several options in a list while
         radios are for selecting one option from many.
-        Add the <code>.inline</code> class to a series of checkboxes or radios
+        Add the `.inline` class to a series of checkboxes or radios
         for controls to appear on the same line.
       controls_input: >
         Most common form control, text-based input fields.
         Includes support for all HTML5 types:
         text, password, datetime, datetime-local, date, month, time, week,
         number, email, url, search, tel, and color.
-        Requires the use of a specified <code>type</code> at all times.
+        Requires the use of a specified `type` at all times.
       controls_select: >
-        Use the default option or specify a <code>multiple="multiple"</code>
+        Use the default option or specify a `multiple="multiple"`
         to show multiple options at once.
       controls_textarea: >
         Form control which supports multiple lines of text.
-        Change <code>rows</code> attribute as necessary.
+        Change the `rows` attribute as necessary.
 
       # layouts
       default_styles: >
         Individual form controls receive styling, but without any required base
-        class on the <code>&lt;form&gt;</code> or large changes in markup.
+        class on the `<form>` or large changes in markup.
         Results in stacked, left-aligned labels on top of form controls.
       horizontal: >
         Right align labels and float them to the left to make them appear on
         the same line as controls.
         Requires the most markup changes from a default form:
-        <ul>
-          <li>Add <code>.form-horizontal</code> to the form</li>
-          <li>Wrap labels and controls in <code>.control-group</code></li>
-          <li>Add <code>.control-label</code> to the label</li>
-          <li>Wrap any associated controls in <code>.controls</code> for proper alignment</li>
-        </ul>
+          * Add `.form-horizontal` to the form
+          * Wrap labels and controls in `.control-group`
+          * Add `.control-label` to the label
+          * Wrap any associated controls in `.controls` for proper alignment
       inline: >
-        Add <code>.form-inline</code> for left-aligned labels and inline-block
+        Add `.form-inline` for left-aligned labels and inline-block
         controls for a compact layout.
       search: >
-        Add <code>.form-search</code> to the form and <code>.search-query</code>
-        to the <code>&lt;input&gt;</code> for an extra-rounded text input.
+        Add `.form-search` to the form and `.search-query`
+        to the `<input>` for an extra-rounded text input.
 
     images:
       dropdown_icons: Dropdown in a button group.
@@ -66,44 +64,44 @@ en:
 
     tables:
       default_style: >
-        For basic styling&mdash;light padding and only horizontal
-        dividers&mdash;add the base class <code>.table</code> to
-        any <code>&lt;table&gt;</code>.
+        For basic styling – light padding and only horizontal
+        dividers – add the base class `.table` to
+        any `<table>`.
       striped: >
-        <code>.table-striped</code>
+        `.table-striped`
         adds zebra-striping to any table row within the
-        <code>&lt;tbody&gt;</code> via the <code>:nth-child</code> CSS selector
+        `<tbody>` via the `:nth-child` CSS selector
         (not available in IE7-IE8).
       bordered: >
-        <code>.table-bordered</code>
+        `.table-bordered`
         adds borders and rounded corners to the table.
       hover: >
-        <code>.table-hover</code>
-        enables a hover state on table rows within a <code>&lt;tbody&gt;</code>.
+        `.table-hover`
+        enables a hover state on table rows within a `<tbody>`.
       condensed: >
-        <code>.table-condensed</code>
+        `.table-condensed`
         makes tables more compact by cutting cell padding in half.
       row_classes: >
         Use contextual classes to color table rows.
 
     typography:
       body_copy: >
-        Bootstrap's global default <code>font-size</code> is
-        <strong>14px</strong>, with a <code>line-height</code> of
-        <strong>20px</strong>. This is applied to the <code>&lt;body&gt;</code>
-        and all paragraphs. In addition, <code>&lt;p&gt;</code> (paragraphs)
+        Bootstrap's global default `font-size` is
+        <strong>14px</strong>, with a `line-height` of
+        <strong>20px</strong>. This is applied to the `<body>`
+        and all paragraphs. In addition, `<p>` (paragraphs)
         receive a bottom margin of half their line-height (10px by default).
-        Make a paragraph stand out by adding <code>.lead</code>.
+        Make a paragraph stand out by adding `.lead`.
 
       headings: >
-        All HTML headings, <code>&lt;h1&gt;</code> through
-        <code>&lt;h6&gt;</code> are available.
+        All HTML headings, `<h1>` through
+        `<h6>` are available.
 
       code_inline: >
-        Use <code>&lt;code&gt;</code> for inline snippets of code.
+        Use `<code>` for inline snippets of code.
       code_blocks: >
-        Use <code>&lt;pre&gt;</code> for multiple lines of code.
+        Use `<pre>` for multiple lines of code.
         Be sure to escape any angle brackets in the code for proper rendering.
             images_placeholders: >
-        Add classes to an <code>&lt;img&gt;</code> element to easily
+        Add classes to an `<img>` element to easily
         style images in any project.

data/lib/style_guide/partial.rb

@@ -1,4 +1,5 @@
 require "nokogiri"
+require "github/markdown"
 
 module StyleGuide
   class Partial
@@ -22,11 +23,7 @@ module StyleGuide
     end
 
     def description
-      @description ||= begin
-        I18n.translate!(id, :scope => [:style_guide, section.id.to_sym])
-      rescue I18n::MissingTranslationData
-        nil
-      end
+      @description ||= GitHub::Markdown.render_gfm(translated_description)
     end
 
     def classes
@@ -51,6 +48,16 @@ module StyleGuide
 
     private
 
+    def style_guide_scope
+      [:style_guide, section.id.to_sym]
+    end
+
+    def translated_description
+      I18n.translate!(id, :scope => style_guide_scope)
+    rescue I18n::MissingTranslationData
+      nil
+    end
+
     def parsed
       @parsed ||= Nokogiri::HTML.parse(content)
     end

data/lib/style_guide/version.rb

@@ -1,3 +1,3 @@
 module StyleGuide
-  VERSION = "0.6.0"
+  VERSION = "0.6.1"
 end

data/spec/lib/style_guide/partial_spec.rb

@@ -63,9 +63,25 @@ describe StyleGuide::Partial do
     end
 
     context "when there is a translation string available" do
-      before { I18n.stub(:translate => "pants") }
+      let(:translated) { "pants" }
 
-      it { should == "pants" }
+      before { I18n.stub(:translate => translated) }
+
+      it { should include "<p>pants" }
+
+      context "when the translated string includes html" do
+        let(:translated) { '`<br>`' }
+
+        it { should include '&lt;br&gt;' }
+      end
+
+      context "when the translated string includes markdown" do
+        let(:translated) { "`meat` *beans* __socks__" }
+
+        it { should include "<code>meat" }
+        it { should include "<em>beans" }
+        it { should include "<strong>socks" }
+      end
     end
   end
 

data/style-guide.gemspec

@@ -7,16 +7,17 @@ Gem::Specification.new do |s|
   s.authors     = ["Doc Ritezel"]
   s.email       = ["doc@pivotallabs.com"]
   s.homepage    = "https://github.com/pivotal/style-guide"
-  s.summary     = "A live style guide for your application."
-  s.description = "Inspired by the Bootstrap guide, style-guide is an engine that lets you see all your styles applied live."
+  s.summary     = "A live style guide for your Rails application."
+  s.description = "Inspired by the Bootstrap guide, style-guide is a Rails engine that lets you see all your styles applied in front of your eyes."
 
   s.files         = `git ls-files`.split( "\n" ) - %w(Gemfile.lock)
   s.test_files    = `git ls-files -- spec/*`.split( "\n" )
-  s.require_paths = ['lib']
+  s.require_paths = ["lib"]
 
   s.add_dependency "rails", "~> 3.2"
   s.add_dependency "jquery-rails", "~> 2.1"
   s.add_dependency "nokogiri", "~> 1.5"
+  s.add_dependency "github-markdown", "~> 0.5"
 
   s.add_development_dependency "foreman"
   s.add_development_dependency "rb-fsevent"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: style-guide
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
   prerelease: 
 platform: ruby
 authors:
@@ -59,6 +59,22 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: github-markdown
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: foreman
   requirement: !ruby/object:Gem::Requirement
@@ -187,8 +203,8 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Inspired by the Bootstrap guide, style-guide is an engine that lets you
-  see all your styles applied live.
+description: Inspired by the Bootstrap guide, style-guide is a Rails engine that lets
+  you see all your styles applied in front of your eyes.
 email:
 - doc@pivotallabs.com
 executables: []
@@ -429,7 +445,7 @@ rubyforge_project:
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: A live style guide for your application.
+summary: A live style guide for your Rails application.
 test_files:
 - spec/controllers/style_guide/style_controller_spec.rb
 - spec/dummy/README.rdoc