first stab at documentation

.yardopts

@@ -0,0 +1,7 @@
+--title 'Docile Documentation'
+
+--no-private
+--hide-void-return
+
+--markup-provider=redcarpet
+--markup=markdown

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2011 Marc Siegel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,75 @@
+# Docile
+
+Definition: *Ready to accept control or instruction; submissive* [[1]]
+
+Tired of overly complex DSL libraries and hairy meta-programming?
+Let's make our Ruby DSLs more *docile*...
+
+[1]: http://www.google.com/search?q=docile+definition   "Google"
+
+## Usage
+
+Let's treat an Array's methods as its own DSL:
+
+``` ruby
+Docile.dsl_eval [] do
+  push 1
+  push 2
+end
+#=> [1, 3]
+```
+
+Mutating (changing) the array is fine, but what you probably really want as your DSL is actually a [Builder Pattern][2].
+
+For example, if you have a PizzaBuilder class that can build a pizza:
+
+``` ruby
+@sauce_level = :extra
+pizza = PizzaBuilder.new.cheese.pepperoni.bacon.sauce(@sauce_level).build
+```
+
+Then you can use this PizzaBuilder class as a DSL:
+
+``` ruby
+@sauce_level = :extra
+pizza = Docile.dsl_eval PizzaBuilder.new do
+  cheese
+  pepperoni
+  bacon
+  sauce @sauce_level
+end.build
+```
+
+[2]: http://stackoverflow.com/questions/328496/when-would-you-use-the-builder-pattern  "Builder Pattern"
+
+## Features
+
+  1.  method lookup falls back from the DSL object to the block's context
+  2.  local variable lookup falls back from the DSL object to the block's context
+  3.  instance variables are from the block's context only
+
+## Installation
+
+``` bash
+$ gem install docile
+```
+
+## Documentation
+
+Documentation hosted on *rubydoc.info*: [Docile Documentation](http://rubydoc.info/gems/docile)
+Or, read the code hosted on *github.com*: [Docile Code](https://github.com/ms-ati/docile)
+
+## Note on Patches/Pull Requests
+
+  * Fork the project.
+  * Setup your development environment with: gem install bundler; bundle install
+  * Make your feature addition or bug fix.
+  * Add tests for it. This is important so I don't break it in a
+    future version unintentionally.
+  * Commit, do not mess with rakefile, version, or history.
+    (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+  * Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2011 Marc Siegel. See LICENSE for details.

Rakefile

@@ -1,9 +1,11 @@
 require "bundler/gem_tasks"
+require "github/markup"
+require "redcarpet"
 require "yard"
 require "yard/rake/yardoc_task"
 
 YARD::Rake::YardocTask.new do |t|
-  OTHER_PATHS = %w(README.md LICENSE)
+  OTHER_PATHS = %w()
   t.files   = ['lib/**/*.rb', OTHER_PATHS]
-  t.options = ['--main', 'README.md']
+  t.options = %w(--markup-provider=redcarpet --markup=markdown)
 end

docile.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   s.authors     = ["Marc Siegel"]
   s.email       = ["msiegel@usainnov.com"]
   s.homepage    = "http://docile.github.com"
-  s.summary     = "Docile helps keep your DSLs tame and well-behaved'"
-  s.description = "Docile handles ruby DSL evaluation best-practices so you can concentrate on your project"
+  s.summary     = "Docile keeps your Ruby DSL's tame and well-behaved"
+  s.description = "Docile turns any Ruby object into a DSL. Especially useful with the Builder pattern."
 
   s.rubyforge_project = "docile"
 
@@ -19,6 +19,10 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_development_dependency "rspec", "~> 2.7.0"
+
+  # Github flavored markdown in YARD documentation
+  # http://blog.nikosd.com/2011/11/github-flavored-markdown-in-yard.html
   s.add_development_dependency "yard"
   s.add_development_dependency "redcarpet"
+  s.add_development_dependency "github-markup"
 end

lib/docile/version.rb

@@ -1,3 +1,3 @@
 module Docile
-  VERSION = "0.1.0"
+  VERSION = "0.9.0"
 end