Merge remote branch 'chris/docs' into docs

doc-src/README.markdown

@@ -51,6 +51,13 @@ To compile (and auto recompile) and preview the site in your browser:
 
 Then open `http://localhost:3000/` in your web browser.
 
+If you find `bin/nanoc3 aco` to be sluggish, try this alternative workflow:
+
+    $ cd doc-src
+    $ export RUBYLIB="../lib:../../haml/lib"
+    $ serve 3000 .. &
+    $ rake watch
+
 ## Documentation on Nanoc
 
 * [Nanoc Homepage](http://nanoc.stoneship.org/)
@@ -84,7 +91,7 @@ Example Metadata is used to associate the example to a mixin in the reference do
     mixin: awesome
     ---
 
-After adding the example and adjusting the metadata, go to the reference page and you can verify that a link to the example has appeared.
+After adding the example and adjusting the metadata, go to the reference page and you can verify that a link to the example has appeared. If the mixin property is omitted, then the example will be a general example for the stylesheet.
 
 ### How to Add New Reference Documentation
 

doc-src/Rakefile

@@ -29,6 +29,7 @@ task :watch do
       `growlnotify -m "Compilation Complete" --image misc/success-icon.png; exit 0`
     rescue Exception => e
       puts ">>> ERROR: #{e.message} <<<"
+      puts e.backtrace.join("\n")
       `growlnotify -m "Compilation Error!" --image misc/error-icon.png; exit 0`
     end
   end

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

@@ -0,0 +1,8 @@
+---
+title: Two Column Layout
+description: A semantic two-column layout
+framework: blueprint
+stylesheet: blueprint/_grid.sass
+example: true
+---
+= render "partials/example"

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

@@ -0,0 +1,19 @@
+.two-col
+  #header
+    %h1 This is the Header
+  #sidebar
+    %ul
+      %li
+        %a(href="#") Nav #1
+      %li
+        %a(href="#") Nav #2
+      %li
+        %a(href="#") Nav #3
+  #content
+    %p
+      Lorem ipsum dolor sit amet,
+      consectetur adipisicing elit, sed do
+      eiusmod tempor incididunt ut labore et
+      dolore magna aliqua.
+  #footer
+    This is the footer.

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

@@ -0,0 +1,16 @@
+!blueprint_grid_columns = 8
+!blueprint_grid_width = 40px
+
+@import blueprint
+
+.two-col
+  +container
+  background-color: #ccc
+  #header, #footer
+    +column(8)
+  #sidebar
+    +column(3)
+  #content
+    +column(5, true)
+  
+ 

doc-src/content/reference/blueprint.haml

@@ -6,16 +6,10 @@ stylesheet: _blueprint.sass
 classnames:
   - reference
 ---
-%h1= item[:title]
 
-= render "partials/breadcrumbs"
-
-%p
+- render 'reference' do
+  %p
     The blueprint module is a simple way of importing all of the most
     commonly used blueprint modules. In addition, it provides
     a single mixin, <code class="mixin">+blueprint</code>, that
     can be used to generate the blueprint css styles.
-
-= render "partials/reference/imports"
-
-= render "partials/reference/mixins"

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

@@ -0,0 +1,7 @@
+- if (examples = examples(@item)).any?
+  %h2 Examples
+  %dl.examples
+    - examples.each do |example|
+      %dt= link_to example.item[:title], example, :target => "_blank"
+      - if example.item[:description]
+        %dd= example.item[:description]

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

@@ -8,7 +8,7 @@
 
     .source-documentation
       = format_doc(mixin.comment)
-      - if (examples = mixin_examples(@item, mixin)).any?
+      - if (examples = examples(@item, mixin)).any?
         %dl.examples
           - examples.each do |example|
             %dt= link_to example.item[:title], example, :target => "_blank"

doc-src/layouts/reference.haml

@@ -4,6 +4,8 @@
 
 = yield
 
+= render "partials/reference/examples"
+
 = render "partials/reference/imports"
 
 = render "partials/reference/constants"

doc-src/lib/stylesheets.rb

@@ -128,13 +128,26 @@ def mixin_signature(mixin)
   mixin.sass_signature(:include)
 end
 
-def mixin_examples(item, mixin)
-  @items.select do |i|
-    i[:example] &&
+def example_items
+  @example_items ||= @items.select{|i| i[:example]}
+end
+
+def examples_for_item(item)
+  @examples ||= {}
+  @examples[item] ||= example_items.select do |i|
     i[:framework] == item[:framework] &&
-    i[:stylesheet] == item[:stylesheet] &&
-    i[:mixin] == mixin.name
-  end.map{|i| i.reps.find{|r| r.name == :default}}
+    i[:stylesheet] == item[:stylesheet]
+  end
+end
+
+def examples(item, mixin = nil)
+  examples = examples_for_item(item)
+  if mixin
+    examples = examples.select {|i| i[:mixin] == mixin.name }
+  else
+    examples = examples.reject {|i| i[:mixin] }
+  end
+  examples.map{|i| i.reps.find{|r| r.name == :default}}
 end