From 1f62e56f545ed8c51560ff142ed9d41819fa3c63 Mon Sep 17 00:00:00 2001 From: Marc Siegel Date: Tue, 6 Dec 2011 17:58:09 -0500 Subject: [PATCH] first stab at documentation --- .yardopts | 7 ++++ LICENSE | 19 +++++++++++ LICENSE.txt | 0 README.md | 75 +++++++++++++++++++++++++++++++++++++++++++ Rakefile | 6 ++-- docile.gemspec | 8 +++-- lib/docile/version.rb | 2 +- 7 files changed, 112 insertions(+), 5 deletions(-) create mode 100644 .yardopts create mode 100644 LICENSE delete mode 100644 LICENSE.txt diff --git a/.yardopts b/.yardopts new file mode 100644 index 0000000..7512589 --- /dev/null +++ b/.yardopts @@ -0,0 +1,7 @@ +--title 'Docile Documentation' + +--no-private +--hide-void-return + +--markup-provider=redcarpet +--markup=markdown diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..dbabafd --- /dev/null +++ b/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. \ No newline at end of file diff --git a/LICENSE.txt b/LICENSE.txt deleted file mode 100644 index e69de29..0000000 diff --git a/README.md b/README.md index e69de29..362c99c 100644 --- a/README.md +++ b/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. diff --git a/Rakefile b/Rakefile index e8730c1..8d91737 100644 --- a/Rakefile +++ b/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 diff --git a/docile.gemspec b/docile.gemspec index 6a74eed..462d261 100644 --- a/docile.gemspec +++ b/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 diff --git a/lib/docile/version.rb b/lib/docile/version.rb index c28ff0d..ec56e6e 100644 --- a/lib/docile/version.rb +++ b/lib/docile/version.rb @@ -1,3 +1,3 @@ module Docile - VERSION = "0.1.0" + VERSION = "0.9.0" end