sinatra-croon 0.0.1

data/README.md

@@ -0,0 +1,43 @@
+# Sinatra::Croon
+
+Allows you to add inline documentation to a Sinatra app and have a web-based
+documentation browser be available to you.
+
+## Usage
+
+    require "sinatra/croon"
+
+    class MyApp < Sinatra::Base
+      register Sinatra::Croon
+    end
+
+## Documentation Format
+
+    # Create an application.
+    #
+    # @param <name>  the name of the application to create
+    # @param [stack] the stack on which to create the application
+    #
+    # @request
+    #   POST /apps.json
+    #   name=example&stack=bamboo-ree-1.8.7
+    # @response
+    #   {
+    #     "id":         1,
+    #     "name":       "example",
+    #     "owner":      "user@example.org",
+    #     "created_at": "Sat Jan 01 00:00:00 UTC 2000",
+    #     "stack":      "bamboo-ree-1.8.7",
+    #     "slug_size":  1000000,
+    #     "repo_size":  500000,
+    #     "dynos":      1,
+    #     "workers":    0
+    #   }
+
+    post "/apps.json" do
+      # do something here
+    end
+
+## Web-based browser
+
+  Sinatra::Croon will create a route at `/docs` to display your documentation.

data/Rakefile

@@ -0,0 +1,58 @@
+require "rubygems"
+require "rake"
+require "rspec"
+require "rspec/core/rake_task"
+
+$:.unshift File.expand_path("../lib", __FILE__)
+require "sinatra/croon"
+
+task :default => :spec
+
+desc "Run all specs"
+Rspec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+desc "Generate RCov code coverage report"
+task :rcov => "rcov:build" do
+  %x{ open coverage/index.html }
+end
+
+Rspec::Core::RakeTask.new("rcov:build") do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+  t.rcov = true
+  t.rcov_opts = [ "--exclude", Gem.default_dir, "--exclude", "spec" ]
+end
+
+######################################################
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name    = "sinatra-croon"
+    s.version = Sinatra::Croon::VERSION
+
+    s.summary     = "Create documentation for an API built in Sinatra."
+    s.description = s.summary
+    s.author      = "David Dollar"
+    s.email       = "ddollar@gmail.com"
+    s.homepage    = "http://daviddollar.org/"
+
+    s.platform = Gem::Platform::RUBY
+    s.has_rdoc = false
+
+    s.files = %w(Rakefile README.markdown) + Dir["{lib,spec}/**/*"]
+    s.require_path = "lib"
+
+    s.add_development_dependency 'rack-test', '~> 0.5.4'
+    s.add_development_dependency 'rake',      '~> 0.8.7'
+    s.add_development_dependency 'rspec',     '~> 2.0.0.beta.5'
+    s.add_development_dependency 'webrat',    '~> 0.7.1'
+
+    s.add_dependency 'haml',      '~> 3.0.12'
+    s.add_dependency 'sinatra',   '~> 1.0'
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler"
+end

data/lib/sinatra/croon/views/docs.haml

@@ -0,0 +1,41 @@
+!!! 5
+
+%html
+
+  %head
+    %title API Documentation
+    %link{ :rel => "stylesheet", :href => "/docs.css" }
+
+  %body
+
+    #content
+
+      %h1
+        %a{ :href => '/' } API Documentation
+
+      - docs.each do |doc|
+
+        .api
+
+          .url
+            %a
+              = doc[:verb].upcase
+              = doc[:uri]
+
+          .description
+            = doc[:description]
+
+          - if (doc[:params] || []).length > 0
+            .params
+              - doc[:params].each do |param|
+                .param
+                  .type{ :class => (param[:required] && "required") }
+                    = (param[:required]) ? "REQUIRED" : "OPTIONAL"
+                  .name= escape_html(param[:name])
+                  .description= param[:description]
+
+          %code.request
+            = display_code doc[:request]
+
+          %code.response
+            = display_code doc[:response]

data/lib/sinatra/croon/views/docs.sass

@@ -0,0 +1,106 @@
+*
+  :font-family Helvetica, Arial, sans-serif
+
+=code_title
+  :display block
+  :padding 6px 10px
+  :font-weight bold
+  :background #ccc
+  :color #333
+  :margin-left -12px
+  :margin-right -12px
+  :margin-top -12px
+  :margin-bottom 12px
+
+h2
+  :background #555
+  :color #fff
+  :border 1px #666 solid
+  :padding 10px
+  a
+    :color #fff
+    :text-decoration none
+
+.api
+  :margin-bottom 24px
+  :background #eee
+  :border 1px #ccc solid
+
+  .url
+    :padding 6px 10px
+    :background #aaa
+    :border-bottom 1px #ccc solid
+    a
+      :color #333
+      :font-size 1.6em
+      :font-weight bold
+      :font-family monospace
+
+  .description
+    :padding 12px
+
+  code
+    :font-family Monaco, monospace
+    :white-space pre
+    :padding 12px
+    :display block
+
+  .params
+    :margin-bottom 10px
+    :padding 12px
+    :display block
+    &:before
+      +code_title
+      :content "Parameters"
+    .param
+      :line-height 30px
+      .name
+        :display inline
+        :font-weight bold
+        :font-family monospace
+        :font-size 1.2em
+      .type
+        :font-weight bold
+        :font-size 0.6em
+        :color #999
+        :display inline-block
+        :width 65px
+      .required
+        :color #333
+      .description
+        :display inline
+
+  .request
+    &:before
+      +code_title
+      :content "Request"
+
+  .response
+    &:before
+      +code_title
+      :content "Response"
+
+body
+  :margin 0
+  
+#content
+  :width 800px
+  :margin-left auto
+  :margin-right auto
+
+#index
+  .section
+    :margin-bottom 20px
+  .summarydoc
+    :border 1px #ccc solid
+    :padding 12px
+    :margin-top 10px
+    :background #eee
+    .path
+      :margin-bottom 10px
+      a
+        :font-family monospace
+        :font-weight bold
+        :font-size 1.4em
+    .description
+      :color #666

data/lib/sinatra/croon.rb

@@ -0,0 +1,108 @@
+require "haml"
+require "sinatra/base"
+
+module Sinatra
+  module Croon
+    VERSION = "0.0.1"
+
+    def self.registered(app)
+      app.helpers Croon::Helpers
+      @app = app
+
+      app.get '/docs.css' do
+        pass do
+          content_type "text/css"
+          template = File.read(File.expand_path("../croon/views/docs.sass", __FILE__))
+          sass template
+        end
+      end
+
+      app.get '/docs' do
+        pass do
+          template = File.read(File.expand_path("../croon/views/docs.haml", __FILE__))
+          haml template, :locals => { :docs => documentation }
+        end
+      end
+    end
+
+    def self.route_added(verb, path, block)
+      return if verb.to_s == "HEAD"
+
+      route_location = caller(1).reject { |line| line =~ /sinatra\/base/ }.first
+      file, line = route_location.split(':')
+      doc = Croon::Parser.parse_route_documentation(file, line.to_i)
+
+      if doc[:description]
+        doc[:verb] = verb
+        doc[:uri] = path
+        @app.documentation << doc
+      end
+    end
+
+    def documentation
+      @documentation ||= []
+    end
+
+    module Helpers
+      def display_code(code)
+        Haml::Filters::Preserve.render(Haml::Filters::Escaped.render(code))
+      end
+
+      def documentation
+        self.class.documentation
+      end
+    end
+
+    module Parser
+      def self.parse_route_documentation(filename, line)
+        all_lines   = File.read(filename).split("\n").reverse
+        index_start = all_lines.length - line + 1
+        num_lines   = all_lines[index_start..-1].index { |l| !['', '#'].include?(l.strip[0..0]) }
+        doc_lines   = all_lines[index_start, num_lines].reverse
+
+        parse_comments(doc_lines)
+      end
+
+      def self.parse_comments(comments)
+        key = :description
+
+        comments.inject({}) do |parsed, comment|
+          case comment.strip
+            when /\A#\s*@param\s+(.+?)\s+(.+)/ then
+              parsed[:params] ||= []
+              required = $1[0..0] == '<'
+              name = $1[1..-2]
+              parsed[:params] << { :name => name, :description => $2, :required => required }
+            when /\A#\s*@(\w+)\s*(.*)\Z/ then
+              key = $1.to_sym
+              parsed[key] ||= []
+              parsed[key]  << $2 if $2
+            when /\A#(.+)\Z/ then
+              parsed[key] ||= []
+              parsed[key]  << $1
+          end
+          parsed
+        end.inject({}) do |flattened, (k, v)|
+          case v.first
+            when String then
+              flattened[k] = strip_left(v.reject { |l| l.strip == "" }.join("\n"))
+            else
+              flattened[k] = v
+          end
+          flattened
+        end
+      end
+
+      def self.strip_left(code)
+        first_line = code.split("\n").first
+        return code unless first_line
+        num_spaces = first_line.match(/\A */)[0].length
+        code.split("\n").map do |line|
+          line[num_spaces..-1]
+        end.join("\n")
+      end
+    end
+  end
+
+  register Croon
+end

data/spec/sinatra/croon_spec.rb

@@ -0,0 +1,84 @@
+require "spec_helper"
+require "sinatra/base"
+require "sinatra/croon"
+
+class MockSinatraApp < Sinatra::Base
+  register Sinatra::Croon
+
+  # Show an application.
+  #
+  # @request GET /apps.json
+  # @response { "status" : "ok" }
+
+  get "/apps.json" do
+    # do something here
+  end
+
+  # Create an application.
+  #
+  # @param <name>  the name of the application to create
+  # @param [stack] the stack on which to create the application
+  #
+  # @request
+  #   POST /apps.json
+  #   name=example&stack=bamboo-ree-1.8.7
+  #
+  # @response
+  #   {
+  #     "id":         1,
+  #     "name":       "example",
+  #     "owner":      "user@example.org",
+  #     "created_at": "Sat Jan 01 00:00:00 UTC 2000",
+  #     "stack":      "bamboo-ree-1.8.7",
+  #     "slug_size":  1000000,
+  #     "repo_size":  500000,
+  #     "dynos":      1,
+  #     "workers":    0
+  #   }
+
+  post "/apps.json" do
+    # do something here
+  end
+end
+
+describe Sinatra::Croon do
+  include Rack::Test::Methods
+  include Webrat::Matchers
+
+  let(:app) { MockSinatraApp.new }
+
+  it "can set a description" do
+    get "/docs"
+    last_response.should have_selector(".description", :content => "Show an application.")
+    last_response.should have_selector(".description", :content => "Create an application.")
+  end
+
+  it "can set params" do
+    get "/docs"
+    last_response.should have_selector(".param") do |param|
+      param.should have_selector(".type.required")
+      param.should have_selector(".name", :content => "name")
+      param.should have_selector(".description", :content => "the name of the application to create")
+    end
+    last_response.should have_selector(".param") do |param|
+      param.should have_selector(".name", :content => "stack")
+      param.should have_selector(".description", :content => "the stack on which to create the application")
+    end
+  end
+
+  it "can set a request" do
+    get "/docs"
+    last_response.should have_selector(".request", :content => "GET /apps.json")
+  end
+
+  it "can set a response" do
+    get "/docs"
+    last_response.should have_selector(".response", :content => '{ "status" : "ok" }')
+  end
+
+  it "has a default style" do
+    get "/docs.css"
+    last_response.should =~ /\.response/
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require "rubygems"
+require "rack/test"
+require "rspec"
+require "webrat" 
+require "webrat/core/matchers"
+
+$:.unshift "lib"
+
+Rspec.configure do |config|
+  config.color_enabled = true
+end

metadata

@@ -0,0 +1,170 @@
+--- !ruby/object:Gem::Specification 
+name: sinatra-croon
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- David Dollar
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-21 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rack-test
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        - 5
+        - 4
+        version: 0.5.4
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 49
+        segments: 
+        - 0
+        - 8
+        - 7
+        version: 0.8.7
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 62196457
+        segments: 
+        - 2
+        - 0
+        - 0
+        - beta
+        - 5
+        version: 2.0.0.beta.5
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: webrat
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 1
+        segments: 
+        - 0
+        - 7
+        - 1
+        version: 0.7.1
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: haml
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 31
+        segments: 
+        - 3
+        - 0
+        - 12
+        version: 3.0.12
+  type: :runtime
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: sinatra
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 1
+        - 0
+        version: "1.0"
+  type: :runtime
+  version_requirements: *id006
+description: Create documentation for an API built in Sinatra.
+email: ddollar@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- Rakefile
+- lib/sinatra/croon.rb
+- lib/sinatra/croon/views/docs.haml
+- lib/sinatra/croon/views/docs.sass
+- spec/sinatra/croon_spec.rb
+- spec/spec_helper.rb
+- README.md
+has_rdoc: true
+homepage: http://daviddollar.org/
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Create documentation for an API built in Sinatra.
+test_files: 
+- spec/sinatra/croon_spec.rb
+- spec/spec_helper.rb