Document selectors in compass modules. This is mostly for upcoming placeholder selectors.

doc-src/layouts/partials/reference/selectors.haml

@@ -0,0 +1,13 @@
+- if (sels = selectors(@item)).any?
+  %h2 Selectors
+
+  - sels.each do |selector|
+    %a{:href=>"#selector-#{selector.identifier}-source", :rel => "view source"} view source
+    %h3.selector{:id=>"selector-#{selector.identifier}"}
+      %a.permalink{:href => "#selector-#{selector.identifier}"}= selector.name
+    .selector-source{:id=>"selector-#{selector.identifier}-source"}
+      %pre.source-code.sass= selector.to_sass
+      %pre.source-code.scss= selector.to_scss
+
+    .source-documentation
+      = format_doc(selector.comment)

doc-src/layouts/reference.haml

@@ -23,3 +23,5 @@
 = render "partials/reference/functions"
 
 = render "partials/reference/mixins"
+
+= render "partials/reference/selectors"

doc-src/lib/stylesheets.rb

@@ -118,6 +118,31 @@ def mixins(item)
   mixins.reject{|m| m.comment =~ /@private/}
 end
 
+def selectors(item)
+  sass_tree = tree(item)
+  # Visitors::CheckNesting.visit(sass_tree)
+  # sass_tree = Visitors::Perform.visit(sass_tree)
+  selectors = []
+  comment = nil
+  sass_tree.children.each do |child|
+    case child
+    when Sass::Tree::RuleNode
+      child.comment = comment && Sass::Tree::CommentNode.clean(comment)
+      comment = nil
+      selectors << child
+    when Sass::Tree::CommentNode
+      comment ||= ""
+      comment << "\n" unless comment.empty?
+      comment << child.docstring
+    else
+      comment = nil
+    end
+  end
+  selectors.reject!{|s| s.comment =~ /@private/}
+  # selectors.select!{|s| s.comment.strip.size > 0} # this would cause only documented selectors to be output
+  selectors
+end
+
 def functions(item)
   sass_tree = tree(item)
   functions = []

doc-src/lib/stylesheets/sass_extensions.rb

@@ -1,6 +1,20 @@
 require 'sass'
 module Sass
   module Tree
+    class RuleNode
+      attr_accessor :comment unless method_defined? :comment
+      def identifier
+        @identifier ||= begin
+                          id = name.gsub(/[^a-zA-Z]+/,"-").downcase
+                          id = id[1..-1] if id[0..0] == "-"
+                          id = id[0..-2] if id[-1..-1] == "-"
+                          id
+                        end
+      end
+      def name
+        @name ||= rule.map{|part| Sass::Script::Node === part ? "\#{#{part.to_sass}}" : part}.join('')
+      end
+    end
     class VariableNode < Node
       attr_accessor :name unless method_defined? :name
       attr_accessor :expr unless method_defined? :expr