From b15f641bd74250403ca17b0989351ade9e4275a5 Mon Sep 17 00:00:00 2001
From: Chris Eppstein <chris@eppsteins.net>
Date: Tue, 26 Jan 2010 22:08:13 -0800
Subject: [PATCH] A system for creating examples.

---
 doc-src/Rules                                 | 21 ++++++++++++++++++
 .../content/examples/blueprint/grid/pull.haml |  1 +
 .../content/examples/blueprint/grid/pull.yaml |  7 ++++++
 .../examples/blueprint/grid/pull/markup.haml  |  5 +++++
 .../examples/blueprint/grid/pull/markup.yaml  |  0
 .../blueprint/grid/pull/stylesheet.sass       | 12 ++++++++++
 .../blueprint/grid/pull/stylesheet.yaml       |  2 ++
 doc-src/content/stylesheets/example.sass      | 11 ++++++++++
 doc-src/content/stylesheets/example.yaml      |  1 +
 doc-src/layouts/example.haml                  | 12 ++++++++++
 doc-src/layouts/example.yaml                  |  1 +
 doc-src/layouts/partials/example.haml         | 22 +++++++++++++++++++
 doc-src/layouts/partials/example.yaml         |  1 +
 .../layouts/partials/reference/mixins.haml    |  9 +++++++-
 doc-src/lib/examples.rb                       | 14 ++++++++++++
 doc-src/lib/stylesheets.rb                    | 13 ++++++++++-
 16 files changed, 130 insertions(+), 2 deletions(-)
 create mode 100644 doc-src/content/examples/blueprint/grid/pull.haml
 create mode 100644 doc-src/content/examples/blueprint/grid/pull.yaml
 create mode 100644 doc-src/content/examples/blueprint/grid/pull/markup.haml
 create mode 100644 doc-src/content/examples/blueprint/grid/pull/markup.yaml
 create mode 100644 doc-src/content/examples/blueprint/grid/pull/stylesheet.sass
 create mode 100644 doc-src/content/examples/blueprint/grid/pull/stylesheet.yaml
 create mode 100644 doc-src/content/stylesheets/example.sass
 create mode 100644 doc-src/content/stylesheets/example.yaml
 create mode 100644 doc-src/layouts/example.haml
 create mode 100644 doc-src/layouts/example.yaml
 create mode 100644 doc-src/layouts/partials/example.haml
 create mode 100644 doc-src/layouts/partials/example.yaml
 create mode 100644 doc-src/lib/examples.rb

diff --git a/doc-src/Rules b/doc-src/Rules
index 12e1b6f1..d5857e8f 100644
--- a/doc-src/Rules
+++ b/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
diff --git a/doc-src/content/examples/blueprint/grid/pull.haml b/doc-src/content/examples/blueprint/grid/pull.haml
new file mode 100644
index 00000000..be90d9dd
--- /dev/null
+++ b/doc-src/content/examples/blueprint/grid/pull.haml
@@ -0,0 +1 @@
+= render "partials/example"
diff --git a/doc-src/content/examples/blueprint/grid/pull.yaml b/doc-src/content/examples/blueprint/grid/pull.yaml
new file mode 100644
index 00000000..5817f484
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/doc-src/content/examples/blueprint/grid/pull/markup.haml b/doc-src/content/examples/blueprint/grid/pull/markup.haml
new file mode 100644
index 00000000..d24be776
--- /dev/null
+++ b/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
diff --git a/doc-src/content/examples/blueprint/grid/pull/markup.yaml b/doc-src/content/examples/blueprint/grid/pull/markup.yaml
new file mode 100644
index 00000000..e69de29b
diff --git a/doc-src/content/examples/blueprint/grid/pull/stylesheet.sass b/doc-src/content/examples/blueprint/grid/pull/stylesheet.sass
new file mode 100644
index 00000000..f4825c60
--- /dev/null
+++ b/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
diff --git a/doc-src/content/examples/blueprint/grid/pull/stylesheet.yaml b/doc-src/content/examples/blueprint/grid/pull/stylesheet.yaml
new file mode 100644
index 00000000..e5219766
--- /dev/null
+++ b/doc-src/content/examples/blueprint/grid/pull/stylesheet.yaml
@@ -0,0 +1,2 @@
+--- 
+title: A New Item
diff --git a/doc-src/content/stylesheets/example.sass b/doc-src/content/stylesheets/example.sass
new file mode 100644
index 00000000..be331c4c
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/doc-src/content/stylesheets/example.yaml b/doc-src/content/stylesheets/example.yaml
new file mode 100644
index 00000000..2fbf0ffd
--- /dev/null
+++ b/doc-src/content/stylesheets/example.yaml
@@ -0,0 +1 @@
+--- {}
diff --git a/doc-src/layouts/example.haml b/doc-src/layouts/example.haml
new file mode 100644
index 00000000..ce73fcfe
--- /dev/null
+++ b/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
diff --git a/doc-src/layouts/example.yaml b/doc-src/layouts/example.yaml
new file mode 100644
index 00000000..2fbf0ffd
--- /dev/null
+++ b/doc-src/layouts/example.yaml
@@ -0,0 +1 @@
+--- {}
diff --git a/doc-src/layouts/partials/example.haml b/doc-src/layouts/partials/example.haml
new file mode 100644
index 00000000..c16d924b
--- /dev/null
+++ b/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)
\ No newline at end of file
diff --git a/doc-src/layouts/partials/example.yaml b/doc-src/layouts/partials/example.yaml
new file mode 100644
index 00000000..2fbf0ffd
--- /dev/null
+++ b/doc-src/layouts/partials/example.yaml
@@ -0,0 +1 @@
+--- {}
diff --git a/doc-src/layouts/partials/reference/mixins.haml b/doc-src/layouts/partials/reference/mixins.haml
index 221818a1..fd599c52 100644
--- a/doc-src/layouts/partials/reference/mixins.haml
+++ b/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
 
diff --git a/doc-src/lib/examples.rb b/doc-src/lib/examples.rb
new file mode 100644
index 00000000..a566e959
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/doc-src/lib/stylesheets.rb b/doc-src/lib/stylesheets.rb
index 1ecd223f..ff60f59c 100644
--- a/doc-src/lib/stylesheets.rb
+++ b/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 => {