Markdown formatting support for source documentation.

doc-src/content/reference/blueprint.haml

@@ -15,6 +15,6 @@
 %h2 Mixins
 
 - mixins(@item).each do |mixin|
-  %h3= mixin_signature mixin
+  %h3.mixin= mixin_signature mixin
 
-  %pre= mixin.comment
+  .source-documentation= format_doc(mixin.comment)

doc-src/content/stylesheets/main.sass

@@ -13,4 +13,16 @@ body
 #sidebar
   +column(6)
   +pull(24, true)
+
+body.reference
+  h3.mixin
+    background-color: #eee
+    border: 3px solid #aaa
+    padding: 0.75em
+    margin-bottom: 0
+  .source-documentation
+    background-color: #eee
+    border: 3px solid #aaa
+    border-top-width: 0
+    padding: 0.75em
   

doc-src/lib/stylesheets.rb

@@ -1,3 +1,4 @@
+require 'rdiscount'
 
 def stylesheets_dir(framework)
   Compass::Frameworks[framework].stylesheets_directory
@@ -61,3 +62,7 @@ def mixin_signature(mixin)
   signature
 end
 
+def format_doc(docstring)
+  RDiscount.new(docstring).to_html
+end
+

frameworks/blueprint/stylesheets/_blueprint.sass

@@ -8,18 +8,23 @@
 @import blueprint/print.sass
 @import blueprint/ie.sass
 
-// Usage examples:
+//
-// As a top-level mixin, apply to any page that includes the stylesheet:
+  ### Usage examples:
-//   +blueprint
+  
-// Scoped by a presentational class:
+  As a top-level mixin, apply to any page that includes the stylesheet:
-//   body.blueprint
+      +blueprint
-//    +blueprint(true)
+
-// Scoped by semantic selectors:
+  Scoped by a presentational class:
-//   body#page-1, body#page-2, body.a-special-page-type
+      body.blueprint
-//     +blueprint(true)
+        +blueprint(true)
-// Deprecated:
+
-//   You can pass the body selector as the first argument when used as a top-level mixin
+  Scoped by semantic selectors:
-//   +blueprint("body#page-1, body#page-2, body.a-special-page-type")
+      body#page-1, body#page-2, body.a-special-page-type
+        +blueprint(true)
+
+  #### Deprecated:
+  You use to be able to pass the body selector as the first argument when used as a top-level mixin
+       +blueprint("body#page-1, body#page-2, body.a-special-page-type")
 =blueprint(!body_selector = "body")
   @if not (!body_selector == "body" or !body_selector == true)
     @debug "[DEPRECATED] To specify a the selector \"#{!body_selector}\" to +blueprint, pass true as the first argument and mix it into #{!body_selector}."