A system for creating examples.

doc-src/Rules

@@ -12,10 +12,23 @@ compile '/images/*/' do
   nil
 end
 
+compile '/examples/*/markup/' do
+  nil
+end
+
+compile '/examples/*/stylesheet/' do
+  nil
+end
+
 compile '/javascripts/*/' do
   nil
 end
 
+compile '/examples/*/' do
+  filter :haml, :ugly => true
+  layout 'example'
+end
+
 compile '/stylesheets/*/' do
   filter :sass, Compass.sass_engine_options
 end
@@ -47,6 +60,14 @@ route '/stylesheets/*/' do
   item.identifier.chop + '.css'
 end
 
+route '/examples/*/markup/' do
+  nil
+end
+
+route '/examples/*/stylesheet/' do
+  nil
+end
+
 route '*' do
   item.identifier + 'index.html'
 end

doc-src/content/examples/blueprint/grid/pull.haml

@@ -0,0 +1 @@
+= render "partials/example"

doc-src/content/examples/blueprint/grid/pull.yaml

@@ -0,0 +1,7 @@
+--- 
+title: Blueprint Pull Example
+description: Uses pull to change the display order of columns.
+framework: blueprint
+stylesheet: blueprint/_grid.sass
+mixin: pull
+example: true

doc-src/content/examples/blueprint/grid/pull/markup.haml

@@ -0,0 +1,5 @@
+.container
+  #one
+    One<br />One<br />One
+  #two
+    Two<br />Two<br />Two

doc-src/content/examples/blueprint/grid/pull/stylesheet.sass

@@ -0,0 +1,12 @@
+!blueprint_grid_columns = 3
+
+@import blueprint/grid.sass
+
+#one
+  +column(2, true)
+  +prepend(1)
+  background-color: #11770E
+#two
+  +column(1)
+  +pull(3, true)
+  background-color: #242677

doc-src/content/examples/blueprint/grid/pull/stylesheet.yaml

@@ -0,0 +1,2 @@
+--- 
+title: A New Item

doc-src/content/stylesheets/example.sass

@@ -0,0 +1,11 @@
+#example
+  width: 100%
+  td
+    border: 2px solid black
+    padding: 6px 4px
+    vertical-align: top
+    width: 48%
+    pre
+      margin: 0
+      height: 200px
+      overflow: auto

doc-src/content/stylesheets/example.yaml

@@ -0,0 +1 @@
+--- {}

doc-src/layouts/example.haml

@@ -0,0 +1,12 @@
+!!! Strict
+%html
+  %head
+    %title
+      #{@item[:title]} - Compass
+    %meta{ :content => "text/html; charset=utf-8", "http-equiv" => "Content-Type" }
+    %link{ :href => "/stylesheets/example.css", :rel => "stylesheet", :type => "text/css", :media => "screen" }
+    %style{:type => "text/css"}= example_css
+  %body{body_attributes(@item)}
+    #container
+      #main
+        = yield

doc-src/layouts/example.yaml

@@ -0,0 +1 @@
+--- {}

doc-src/layouts/partials/example.haml

@@ -0,0 +1,22 @@
+%h1= @item[:title]
+
+%table#example{:cellspacing=>"0", :cellpadding=>"0", :border=>"0"}
+  %tr.source
+    %th HTML
+    %th Sass
+  %tr.source
+    %td.markup
+      %pre
+        %code= h(example_html)
+    %td.stylesheet
+      %pre
+        %code= h(example_sass)
+  %tr.output
+    %th Display
+    %th Generated CSS
+  %tr.output
+    %td.markup
+      = example_html
+    %td.stylesheet
+      %pre
+        %code= h(example_css)

doc-src/layouts/partials/example.yaml

@@ -0,0 +1 @@
+--- {}

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

@@ -6,7 +6,14 @@
     %h3.mixin{:id=>"mixin-#{mixin.name}"}
       %a.permalink{:href => "#mixin-#{mixin.name}"}= mixin_signature mixin
 
-    .source-documentation= format_doc(mixin.comment)
+    .source-documentation
+      = format_doc(mixin.comment)
+      - if (examples = mixin_examples(@item, mixin)).any?
+        %dl.examples
+          - examples.each do |example|
+            %dt= link_to example.item[:title], example, :target => "_blank"
+            - if example.item[:description]
+              %dd= example.item[:description]
     = mixin_source_dialog(mixin) do
       %pre.source-code.sass= mixin.to_sass
 

doc-src/lib/examples.rb

@@ -0,0 +1,14 @@
+def example_html
+  markup_item = @item.children.detect{|child| child.identifier =~ /markup/}
+  haml = markup_item.reps.find { |r| r.name == :default }.content_at_snapshot(:raw)
+  Haml::Engine.new(haml).render
+end
+
+def example_sass
+  markup_item = @item.children.detect{|child| child.identifier =~ /stylesheet/}
+  markup_item.reps.find { |r| r.name == :default }.content_at_snapshot(:raw)
+end
+
+def example_css
+  Sass::Engine.new(example_sass, Compass.sass_engine_options.merge(:line_comments => false)).render
+end

doc-src/lib/stylesheets.rb

@@ -33,7 +33,8 @@ def reference_path(options)
   path = stylesheet_path(stylesheet)
   if path
     item = @items.detect do |i|
-      i[:stylesheet] == path
+      i[:stylesheet] == path &&
+      i.identifier =~ /^\/reference/
     end
     if item
       rep = item.reps.find { |r| r.name == :default }
@@ -121,6 +122,16 @@ def mixin_signature(mixin)
   mixin.sass_signature(:include)
 end
 
+def mixin_examples(item, mixin)
+  @items.select do |i|
+    i[:example] &&
+    i[:framework] == item[:framework] &&
+    i[:stylesheet] == item[:stylesheet] &&
+    i[:mixin] == mixin.name
+  end.map{|i| i.reps.find{|r| r.name == :default}}
+end
+  
+
 def mixin_source_dialog(mixin, &block)
   vars = {
     :html => {