kss 0.1.1 → 0.1.2

data/README.md

@@ -1,19 +1,74 @@
 # Knyle Style Sheets
 
-This is a ruby library for parsing KSS documented stylesheets and generating styleguides.
+Inspired by [TomDoc](http://tomdoc.org), KSS attempts to provide a methodology for writing maintainable, documented CSS within a team. Specifically, KSS is a documentation specification and styleguide format. It is **not** a preprocessor, CSS framework, naming convention, or specificity guideline.
 
-Inspired by [TomDoc](http://tomdoc.org), KSS attempts to provide a methodology for writing maintainable, documented CSS within a team. Specifically, KSS is a CSS structure, documentation specification, and styleguide format. It is **not** a preprocessor, CSS framework, naming convention, or specificity guideline.
+* **[The Spec (What KSS is)](https://github.com/kneath/kss/blob/master/SPEC.md)**
+* **[Example living styleguide](https://github.com/kneath/kss/tree/master/example)**
 
-## Spec
+## KSS in a nutshell
 
-If you would like to learn more about the methodology and ideas behind Knyle Style Sheets, you should read SPEC.md. It contains the documenting syntax and styleguide guidelines.
+The methodology and ideas behind Knyle Style Sheets are contained in [SPEC.md](https://github.com/kneath/kss/blob/master/SPEC.md). At it's core, KSS is a documenting syntax for CSS.
+
+```css
+/*
+A button suitable for giving stars to someone.
+
+:hover             - Subtle hover highlight.
+.stars-given       - A highlight indicating you've already given a star.
+.stars-given:hover - Subtle hover highlight on top of stars-given styling.
+.disabled          - Dims the button to indicate it cannot be used.
+
+Styleguide 2.1.3.
+*/
+a.button.star{
+  ...
+}
+a.button.star.stars-given{
+  ...
+}
+a.button.star.disabled{
+  ...
+}
+```
 
 ## Ruby Library
 
-This repository includes a ruby library suitable for parsing SASS, SCSS, and CSS documented with KSS guidelines.
+This repository includes a ruby library suitable for parsing SASS, SCSS, and CSS documented with KSS guidelines. To use the library, include it in your project as a gem from <https://rubygems.org/gems/kss>. Then, create a parser and explore your KSS.
+
+```ruby
+styleguide = Kss::Parser.new("#{RACK_ROOT}public/stylesheets")
+
+styleguide.section('2.1.1')
+# => <Kss::Section>
+
+styleguide.section('2.1.1').description
+# => "A button suitable for giving stars to someone."
+
+styleguide.section('2.1.1').modifiers.first
+# => <Kss::Modifier>
+
+styleguide.section('2.1.1').modifiers.first.name
+# => ':hover'
+
+styleguide.section('2.1.1').modifiers.first.class_name
+# => 'pseudo-class-hover'
+
+styleguide.section('2.1.1').modifiers.first.first.description
+# => 'Subtle hover highlight'
+
+```
 
 The library is also fully TomDoc'd, completing the circle of life.
 
+## Generating styleguides
+
+The documenting syntax and ruby library are intended to generate styleguides automatically. To do this, you'll need to leverage a small javascript library that generates class styles for pseudo-class styles (`:hover`, `:disabled`, etc).
+
+* [kss.coffee](https://github.com/kneath/kss/blob/master/lib/kss.coffee)
+* [kss.js](https://github.com/kneath/kss/blob/master/lib/kss.js) (compiled js)
+
+For an example of how to generate a styleguide, check out the [`example`](https://github.com/kneath/kss/tree/master/example) sinatra application.
+
 ## Development
 
 To hack on KSS, you'll need to install dependencies with `bundle install`. Run tests with `rake`.

data/lib/kss.coffee

@@ -0,0 +1,38 @@
+# This class scans your stylesheets for pseudo classes, then inserts a new CSS
+# rule with the same properties, but named 'psuedo-class-{{name}}'.
+#
+# Supported pseudo classes: hover, disabled.
+#
+# Example:
+#
+#   a:hover{ color:blue; }
+#   => a.pseudo-class-hover{ color:blue; }
+class KssStateGenerator
+  constructor: ->
+    hover = /:hover/
+    disabled = /:disabled/
+
+    try
+      for stylesheet in document.styleSheets
+        idxs = []
+        for rule, idx in stylesheet.cssRules
+          if rule.type is CSSRule.STYLE_RULE and (hover.test(rule.selectorText) or disabled.test(rule.selectorText))
+            @insertRule(rule.cssText.replace(':', '.pseudo-class-'))
+
+  # Takes a given style and attaches it to the current page.
+  #
+  # rule - A CSS rule String (ex: ".test{ display:none; }").
+  #
+  # Returns nothing.
+  insertRule: (rule) ->
+    headEl = document.getElementsByTagName('head')[0]
+    styleEl = document.createElement('style')
+    styleEl.type = 'text/css'
+    if styleEl.styleSheet
+      styleEl.styleSheet.cssText = rule
+    else
+      styleEl.appendChild(document.createTextNode(rule))
+
+    headEl.appendChild(styleEl)
+
+new KssStateGenerator

data/lib/kss/parser.rb

@@ -13,17 +13,27 @@ module Kss
 
       Dir["#{base_path}/**/*.*"].each do |filename|
         root_node = Sass::SCSS::Parser.new(File.read(filename), filename).parse
-        root_node.children.each do |node|
-          next unless node.is_a? Sass::Tree::CommentNode
-          comment_text = self.class.clean_comments node.value[0]
+        parse_node(root_node, filename)
 
-          if self.class.kss_block? comment_text
-            base_name = File.basename(filename)
-            section = Section.new(comment_text, base_name)
-            @sections[section.section] = section
-          end
+      end
+    end
+
+    def parse_node parent_node, filename
+      parent_node.children.each do |node|
+        unless node.is_a? Sass::Tree::CommentNode
+          parse_node(node, filename) if node.has_children
+          next
+        end
+        comment_text = self.class.clean_comments node.value[0]
+
+        if self.class.kss_block? comment_text
+          base_name = File.basename(filename)
+          section = Section.new(comment_text, base_name)
+          @sections[section.section] = section
         end
       end
+
+      parent_node
     end
 
     # Public: Takes a cleaned (no comment syntax like // or /* */) comment
@@ -34,7 +44,7 @@ module Kss
       return false unless cleaned_comment.is_a? String
 
       possible_reference = cleaned_comment.split("\n\n").last
-      possible_reference =~ /Styleguide \d/i
+      possible_reference =~ /Styleguide \d/
     end
 
     # Takes the raw comment text including comment syntax and strips all
@@ -53,11 +63,13 @@ module Kss
       text.gsub!(/^\/\*/, '') # starting block
       text.gsub!(/\*\/$/, '') # ending block
 
+      text.gsub!(/^[ \t]+/, '') # remove leading whitespace
+
       text.strip!
       text
     end
 
-    # Finds the Section for a given styleguide reference
+    # Public: Finds the Section for a given styleguide reference.
     #
     # Returns a Section for a reference, or a blank Section if none found.
     def section(reference)

data/lib/kss/version.rb

@@ -1,3 +1,3 @@
 module Kss
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/test/fixtures/scss/nested.scss

@@ -0,0 +1,12 @@
+// Your standard form element.
+//
+// Styleguide 3.0.0
+form {
+
+  // Your standard text input box.
+  //
+  // Styleguide 3.0.1
+  input[type="text"] {
+    border: 1px solid #ccc;
+  }
+}

data/test/parser_test.rb

@@ -26,6 +26,17 @@ comment
  * Styleguide 2.2.1. */
 comment
 
+  @indented_css_comment = <<comment
+  /*
+  A button suitable for giving stars to someone.
+  
+  .star-given - A highlight indicating you've already given a star.
+  .disabled   - Dims the button to indicate it cannot be used.
+  
+  Styleguide 2.2.1.
+  */
+comment
+
   @cleaned_css_comment = <<comment
 A button suitable for giving stars to someone.
 
@@ -53,6 +64,13 @@ comment
       Kss::Parser.clean_comments(@css_comment)
     assert_equal @cleaned_css_comment,
       Kss::Parser.clean_comments(@starred_css_comment)
+    assert_equal @cleaned_css_comment,
+      Kss::Parser.clean_comments(@indented_css_comment)
+  end
+
+  test "parses nested SCSS documents" do
+    assert_equal "Your standard form element.", @scss_parsed.section('3.0.0').description
+    assert_equal "Your standard text input box.", @scss_parsed.section('3.0.1').description
   end
 
-end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: kss
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 31
   prerelease: 
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Kyle Neath
@@ -15,11 +15,10 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-12-02 00:00:00 -08:00
+date: 2011-12-07 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: sass
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
@@ -32,6 +31,7 @@ dependencies:
         - 1
         version: "3.1"
   type: :runtime
+  name: sass
   version_requirements: *id001
 description: "  Inspired by TomDoc, KSS attempts to provide a methodology for writing\n  maintainable, documented CSS within a team. Specifically, KSS is a CSS\n  structure, documentation specification, and styleguide format.\n\n  This is a ruby library for parsing KSS documented CSS and generating\n  styleguides.\n"
 email: kneath@gmail.com
@@ -49,9 +49,11 @@ files:
 - lib/kss/parser.rb
 - lib/kss/section.rb
 - lib/kss/version.rb
+- lib/kss.coffee
 - lib/kss.rb
 - test/fixtures/css/buttons.css
 - test/fixtures/scss/buttons.scss
+- test/fixtures/scss/nested.scss
 - test/helper.rb
 - test/parser_test.rb
 - test/section_test.rb