From 48d2956a57098e855d829a8160542b63475d09c8 Mon Sep 17 00:00:00 2001 From: Thomas Reynolds Date: Fri, 18 Feb 2011 16:25:18 -0800 Subject: [PATCH] features docs --- docs/lib/middleman.html | 168 -------------------------------------- lib/middleman/features.rb | 105 ++++++++++++++++++++---- middleman.gemspec | 1 + 3 files changed, 90 insertions(+), 184 deletions(-) delete mode 100644 docs/lib/middleman.html diff --git a/docs/lib/middleman.html b/docs/lib/middleman.html deleted file mode 100644 index 12cc3792..00000000 --- a/docs/lib/middleman.html +++ /dev/null @@ -1,168 +0,0 @@ - - - - - middleman.rb - - - -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

middleman.rb

-
- # -
-

Middleman is a static site renderer that provides all the conveniences of - a modern web stack, like Ruby on Rails, while remaining focused on building - the fastest, most-professional sites possible

- -

Install Middleman:

- -
 gem install middleman
-
- -

To accomplish its goals, Middleman supports provides access to:

- -

Command-line tools:

- -
    -
  • mm-init: A tool for creating to new static sites.
    • -
  • mm-server: A tool for rapidly developing your static site.
    • -
  • mm-build: A tool for exporting your site into optimized HTML, CSS & JS.
    • -
- - -

Tons of templating languages including:

- -
    -
  • ERB (.erb)
    • -
  • Interpolated String (.str)
    • -
  • Sass (.sass)
    • -
  • Scss (.scss)
    • -
  • Haml (.haml)
    • -
  • Sass (.sass)
    • -
  • Less CSS (.less)
    • -
  • Builder (.builder)
    • -
  • Liquid (.liquid)
    • -
  • RDiscount (.markdown)
    • -
  • RedCloth (.textile)
    • -
  • RDoc (.rdoc)
    • -
  • Radius (.radius)
    • -
  • Markaby (.mab)
    • -
  • Nokogiri (.nokogiri)
    • -
  • Mustache (.mustache)
    • -
  • CoffeeScript (.coffee)
    • -
- - -

Compile-time Optimiztions

- -
    -
  • Javascript Minifiers: YUI, Google Closure & UglifyJS
    • -
  • Smush.it Image Compression
    • -
  • CSS Minification
    • -
- - -

Robust Extensions:

- -

Add your own runtime and build-time features!

- -

Next Steps:

- - - 		- 

-      

-        

-          #
-        

-        
 Setup out load paths

-      		
-        
libdir = File.dirname(__FILE__)
-$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)

-      

-        

-          #
-        

-        
 Require Rubygems (probably not necessary)

-      		
-        
require 'rubygems'

-      

-        

-          #
-        

-        
 Top-level Middleman object

-      		
-        
module Middleman

-      

-        

-          #
-        

-        
 Auto-load modules on-demand

-      		
-        
  autoload :Server, "middleman/server"
-  

-      

-        

-          #
-        

-        
 Custom Renderers

-      		
-        
  module Renderers
-    autoload :Haml, "middleman/renderers/haml"
-    autoload :Sass, "middleman/renderers/sass"
-  end

-      

-        

-          #
-        

-        
 Features API

-
-      		
-        
  autoload :Features, "middleman/features"
-end

-      

-

-
diff --git a/lib/middleman/features.rb b/lib/middleman/features.rb
index 364c4a41..23f69abd 100644
--- a/lib/middleman/features.rb
+++ b/lib/middleman/features.rb
@@ -1,18 +1,81 @@
+# Middleman provides an extension API which allows you to hook into the
+# lifecycle of a page request, or static build, and manipulate the output.
+# Internal to Middleman, these extensions are called "features," but we use
+# the exact same API as is made available to the public.
+#
+# A Middleman extension looks like this:
+#
+#     module MyExtension
+#       class << self
+#         def registered(app)
+#           # My Code
+#         end
+#       end
+#     end
+#
+# In your `config.rb`, you must load your extension (if it is not defined in
+# that file) and call `activate`.
+#
+#     require "my_extension"
+#     activate MyExtension
+#
+# This will call the `registered` method in your extension and provide you 
+# with the `app` parameter which is a Middleman::Server context. From here 
+# you can choose to respond to requests for certain paths or simply attach 
+# Rack middleware to the stack.
+#
+# The built-in features cover a wide range of functions. Some provide helper
+# methods to use in your views. Some modify the output on-the-fly. And some
+# apply computationally-intensive changes to your final build files.
+
 module Middleman::Features
+
+  # RelativeAssets allow any asset path in dynamic templates to be either
+  # relative to the root of the project or use an absolute URL.
   autoload :RelativeAssets,      "middleman/features/relative_assets"
-  autoload :AssetHost,           "middleman/features/asset_host"
-  autoload :CacheBuster,         "middleman/features/cache_buster"
-  autoload :DefaultHelpers,      "middleman/features/default_helpers"
-  autoload :AutomaticImageSizes, "middleman/features/automatic_image_sizes"
-  autoload :UglyHaml,            "middleman/features/ugly_haml"
-  autoload :MinifyCss,           "middleman/features/minify_css"
-  autoload :MinifyJavascript,    "middleman/features/minify_javascript"
-  autoload :Slickmap,            "middleman/features/slickmap"
-  autoload :SmushPngs,           "middleman/features/smush_pngs"
-  autoload :CodeRay,             "middleman/features/code_ray"
-  autoload :Lorem,               "middleman/features/lorem"
-  # autoload :LiveReload,          "middleman/features/live_reload"
   
+  # AssetHost allows you to setup multiple domains to host your static assets.
+  # Calls to asset paths in dynamic templates will then rotate through each of
+  # the asset servers to better spread the load.
+  autoload :AssetHost,           "middleman/features/asset_host"
+  
+  # CacheBuster adds a query string to assets in dynamic templates to avoid
+  # browser caches failing to update to your new content.
+  autoload :CacheBuster,         "middleman/features/cache_buster"
+  
+  # DefaultHelpers are the built-in dynamic template helpers.
+  autoload :DefaultHelpers,      "middleman/features/default_helpers"
+  
+  # AutomaticImageSizes inspects the images used in your dynamic templates and
+  # automatically adds width and height attributes to their HTML elements.
+  autoload :AutomaticImageSizes, "middleman/features/automatic_image_sizes"
+  
+  # UglyHaml enables the non-indented output format from Haml templates. Useful
+  # for somewhat obfuscating the output and hiding the fact that you're using Haml.
+  autoload :UglyHaml,            "middleman/features/ugly_haml"
+  
+  # MinifyCss uses the YUI compressor to shrink CSS files
+  autoload :MinifyCss,           "middleman/features/minify_css"
+  
+  # MinifyJavascript uses the YUI compressor to shrink JS files
+  autoload :MinifyJavascript,    "middleman/features/minify_javascript"
+  
+  # Slickmap (http://astuteo.com/slickmap/) is a beautiful sitemap tool which 
+  # will attempt to generate a `sitemap.html` file from your project.
+  autoload :Slickmap,            "middleman/features/slickmap"
+  
+  # SmushPngs uses Yahoo's Smush.it API to compresses PNGs and JPGs. Often times
+  # the service can decrease the size of Photoshop-exported images by 30-50%
+  autoload :SmushPngs,           "middleman/features/smush_pngs"
+  
+  # CodeRay is a syntax highlighter.
+  autoload :CodeRay,             "middleman/features/code_ray"
+  
+  # Lorem provides a handful of helpful prototyping methods to generate words,
+  # paragraphs, fake images, names and email addresses.
+  autoload :Lorem,               "middleman/features/lorem"
+  
+  # The Feature API is itself a Feature. Mind blowing!
   class << self
     def registered(app)
       app.extend ClassMethods
@@ -21,13 +84,23 @@ module Middleman::Features
   end
   
   module ClassMethods
+    # This method is available in the project's `config.rb`. 
+    # It takes a underscore-separated symbol, finds the appropriate
+    # feature module and includes it.
+    #   
+    #     activate :lorem
+    #
+    # Alternatively, you can pass in a Middleman feature module directly.
+    #
+    #     activate MyFeatureModule
     def activate(feature_name)
-      mod_name = feature_name.to_s.camelize
-      if Middleman::Features.const_defined?(mod_name)
-        register Middleman::Features.const_get(mod_name)
-      end
+      feature_name = feature_name.to_s if feature_name.class == Symbol
+      feature_name = Middleman::Features.const_get(feature_name.camelize) if feature_name.class == String if Middleman::Features.const_defined?(mod_name)
+    
+      register feature_name
     end
     
+    # Deprecated API. Please use `activate` instead.
     def enable(feature_name)
       $stderr.puts "Warning: Feature activation has been renamed from enable to activate"
       activate(feature_name)
diff --git a/middleman.gemspec b/middleman.gemspec
index 884585bc..ad004b3b 100644
--- a/middleman.gemspec
+++ b/middleman.gemspec
@@ -39,5 +39,6 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency("less", ["~> 1.2.0"])
   s.add_development_dependency("cucumber", ["~> 0.10.0"])
   s.add_development_dependency("rspec", [">= 0"])
+  s.add_development_dependency("rocco", [">= 0"])
 end