css-annotate 1.0.0

data/CHANGELOG

@@ -0,0 +1,10 @@
+2010-11-11 version 1.0.0
+
+Changed options so --commented shows only commented rules.
+
+Included Compass in dependencies.
+
+
+2010-11-11 version 0.1.0
+
+The first release

data/Gemfile

@@ -0,0 +1,7 @@
+source :rubygems
+gemspec
+
+group :development do
+  gem "thin"
+  gem "compass"
+end

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Assaf Arkin
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,9 @@
+  Usage:
+    css-annotate [options] filename
+
+  Options:
+    --commented      Show only rules preceded by a comment
+    --syntax [name]  Either sass or scss (default)
+
+
+http://labnotes.org/wp-content/uploads/2010/11/Your-CSS-annotated.png

data/Rakefile

@@ -0,0 +1,42 @@
+require "rake/testtask"
+
+spec = Gem::Specification.load(Dir["*.gemspec"].first)
+
+desc "Build the Gem"
+task :build do
+  sh "gem build #{spec.name}.gemspec"
+end
+
+desc "Install #{spec.name} locally"
+task :install=>:build do
+  sudo = "sudo" unless File.writable?( Gem::ConfigMap[:bindir])
+  sh "#{sudo} gem install #{spec.name}-#{spec.version}.gem"
+end
+
+desc "Push new release to gemcutter and git tag"
+task :push=>["test", "build"] do
+  sh "git push"
+  puts "Tagging version #{spec.version} .."
+  sh "git tag v#{spec.version}"
+  sh "git push --tag"
+  puts "Building and pushing gem .."
+  sh "gem push #{spec.name}-#{spec.version}.gem"
+end
+
+desc "Run all tests"
+Rake::TestTask.new do |task|
+  task.test_files = FileList['test/**/*_test.rb']
+  if Rake.application.options.trace
+    #task.warning = true
+    task.verbose = true
+  elsif Rake.application.options.silent
+    task.ruby_opts << "-W0"
+  else
+    task.verbose = true
+  end
+    task.ruby_opts << "-I."
+end
+
+task :clobber do
+  rm_rf %w{*.gem}
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/bin/css-annotate

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+require "css/annotate"
+if filename = ARGV[0]
+  options = {}
+  if (i = ARGV.index("--syntax")) && ARGV[i+1]
+    options[:syntax] = ARGV[i + 1].to_sym
+    ARGV[i,2] = []
+  end
+  options[:all] = !ARGV.delete("--commented")
+  $stdout << CSS::Annotate.new(ARGV[0], options).to_html
+else
+  print <<-TEXT
+Usage:
+  css-annotate [options] filename
+
+Options:
+  --commented      Show only rules preceded by a comment
+  --syntax [name]  Either sass or scss (default)
+
+  TEXT
+  exit -1
+end

data/css-annotate.gemspec

@@ -0,0 +1,24 @@
+$: << File.dirname(__FILE__) + "/lib"
+
+Gem::Specification.new do |spec|
+  spec.name           = "css-annotate"
+  spec.version        = IO.read("VERSION")
+  spec.author         = "Assaf Arkin"
+  spec.email          = "assaf@labnotes.org"
+  spec.homepage       = "http://github.com/assaf/#{spec.name}"
+  spec.summary        = "The Annotated CSS tells you which style to use where."
+  spec.description    = "Uses in-line docs to map the stylesheet. Supports CSS and SCSS."
+  spec.post_install_message = "To get started, run the command css-annotate"
+
+  spec.files          = Dir["{bin,lib,test}/**/*", "CHANGELOG", "VERSION", "MIT-LICENSE", "README.rdoc", "Rakefile", "Gemfile", "*.gemspec"]
+  spec.executable     = "css-annotate"
+
+  spec.has_rdoc         = true
+  spec.extra_rdoc_files = "README.rdoc", "CHANGELOG"
+  spec.rdoc_options     = "--title", "#{spec.name} #{spec.version}", "--main", "README.rdoc",
+                          "--webcvs", "http://github.com/assaf/#{spec.name}"
+
+  spec.required_ruby_version = '>= 1.8.7'
+  spec.add_dependency "compass", "~>0.10"
+  spec.add_dependency "haml", "~>3.0"
+end

data/lib/css-annotate.rb

@@ -0,0 +1 @@
+require "css/annotate"

data/lib/css/annotate.rb

@@ -0,0 +1,80 @@
+require "haml"
+require "sass/engine"
+require "compass"
+require "erb"
+require "cgi"
+
+module CSS
+  class Annotate
+
+    DEFAULT_OPTIONS = { :syntax=>:scss }
+
+    def initialize(filename, options = {})
+      @filename = filename
+      @options = DEFAULT_OPTIONS.merge(options)
+      paths = @options[:load_paths] || []
+      paths.push File.dirname(@filename)
+      paths.concat Compass::Frameworks::ALL.map { |framework| framework.stylesheets_directory }
+      @options[:load_paths] = paths
+    end
+
+    attr_reader :filename, :options, :rows
+
+    def annotate
+      $stderr << options.inspect
+      engine = Sass::Engine.new(IO.read(filename), options)
+      tree = engine.to_tree
+      tree.perform!(Sass::Environment.new)
+      resolve_rules tree
+      @rows = to_rows(tree)
+    end
+
+    def h(raw)
+      CGI.escapeHTML(raw.to_s)
+    end
+
+    def to_html
+      rows = annotate
+      ERB.new(IO.read(File.dirname(__FILE__) + "/annotate/template.erb")).run(binding)
+    end
+
+    def styles
+      Sass::Engine.new(IO.read(File.dirname(__FILE__) + "/annotate/style.scss"), :syntax=>:scss).render
+    end
+
+  protected
+
+    def resolve_rules(parent)
+      parent.children.each do |node|
+        if node.respond_to?(:parsed_rules)
+          rules = parent.respond_to?(:resolved_rules) ? parent.resolved_rules : nil
+          node.resolved_rules = node.parsed_rules.resolve_parent_refs(rules)
+          resolve_rules node
+        end
+      end
+    end
+
+    def to_rows(parent)
+      rows = []
+      nodes = parent.children
+      nodes.each_with_index do |node, i|
+        if Sass::Tree::RuleNode === node
+          if i > 0 && (prev = nodes[i - 1]) && Sass::Tree::CommentNode === prev
+            comment = prev.value.gsub(/(^\/\*\s*|\s*\*\/$)/, "")
+          end
+          if comment || options[:all]
+            selector = (node.resolved_rules || node.parsed_rules).to_a.to_s
+            style = "#{selector} {\n"
+            style << node.children.select { |child| Sass::Tree::PropNode === child }.
+              map { |prop| "  #{prop.resolved_name}: #{prop.resolved_value};" }.join("\n")
+            style << "}\n"
+            rows << { :comment=>comment, :selector=>selector, :style=>style }
+          end
+        end
+        rows.concat to_rows(node) if node.has_children
+      end
+      rows
+    end
+
+  end
+end

data/lib/css/annotate/style.scss

@@ -0,0 +1,56 @@
+body {
+  margin: 0;
+  padding: 0;
+  font-family: "Helvetica";
+}
+/* Place on annotation table */
+table.annotated {
+  width: 100%;
+  margin: 0;
+  padding: 0;
+  border-collapse: collapse;
+  border-bottom: 1px solid #ccc;
+
+  /* Apply to column that contains CSS selector/comment */
+  td.comment {
+    vertical-align: top;
+    padding: 0.3em 2em 0.6em 1em;
+
+    h2 {
+      font-size: 12pt;
+      margin: 0 0 0.1em 0;
+      color: #444;
+    }
+
+    blockquote {
+      padding: 0;
+      margin: 0;
+    }
+  }
+
+  /* Apply to column that contains CSS style */
+  td.code {
+    background: #eef;
+    vertical-align: top;
+    padding: 0.3em 1em 0.6em 2em;
+    border-left: 1px solid #ccc;
+  }
+
+  tr:hover td {
+    background: #ddf;
+  }
+}
+.footer {
+  padding: 1em 1em;
+  color: #888;
+
+  /* Use this to style filename in footer */
+  .filename {
+    border: 1px solid #eee;
+    padding: 0 0.3em;
+  }
+  a {
+    text-decoration: none;
+    color: #000;
+  }
+}

data/lib/css/annotate/template.erb

@@ -0,0 +1,23 @@
+<html>
+  <head>
+    <title>Your CSS, annotated</title>
+    <style><%= styles %></style>
+  </head>
+  <body>
+    <table class="annotated">
+      <% rows.each do |row| %>
+        <tr>
+          <td class="comment">
+            <h2><%= h row[:selector] %></h2>
+            <blockquote><%= h row[:comment] %></blockquote>
+          </div></td>
+          <td class="code"><pre><%= h row[:style]%></pre></td>
+        </tr>
+      <% end %>
+    <table>
+    <div class="footer">
+      Generated from <span class="filename"><%= filename %></span> on
+      <%= Time.now.strftime("%c") %> by <a href="http://github.com/assaf/css-annotate">CSS Annotate</a>
+    </div>
+  </body>
+</html>

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification 
+name: css-annotate
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Assaf Arkin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-11 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: compass
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 31
+        segments: 
+        - 0
+        - 10
+        version: "0.10"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: haml
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        version: "3.0"
+  type: :runtime
+  version_requirements: *id002
+description: Uses in-line docs to map the stylesheet. Supports CSS and SCSS.
+email: assaf@labnotes.org
+executables: 
+- css-annotate
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- CHANGELOG
+files: 
+- bin/css-annotate
+- lib/css/annotate/style.scss
+- lib/css/annotate/template.erb
+- lib/css/annotate.rb
+- lib/css-annotate.rb
+- CHANGELOG
+- VERSION
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- Gemfile
+- css-annotate.gemspec
+has_rdoc: true
+homepage: http://github.com/assaf/css-annotate
+licenses: []
+
+post_install_message: To get started, run the command css-annotate
+rdoc_options: 
+- --title
+- css-annotate 1.0.0
+- --main
+- README.rdoc
+- --webcvs
+- http://github.com/assaf/css-annotate
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 57
+      segments: 
+      - 1
+      - 8
+      - 7
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: The Annotated CSS tells you which style to use where.
+test_files: []
+