sinatra-api-docs 0.1.1

data/Rakefile

@@ -0,0 +1,57 @@
+require "rubygems"
+require "rake"
+require "rspec"
+require "rspec/core/rake_task"
+
+$:.unshift File.expand_path("../lib", __FILE__)
+require "sinatra/api_docs"
+
+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-api-docs"
+    s.version = Sinatra::APIDocs::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 'rake',    '~> 0.8.7'
+    s.add_development_dependency 'rspec',   '~> 2.0.0.beta.5'
+
+    s.add_dependency 'haml',      '~> 3.0.12'
+    s.add_dependency 'json_pure', '~> 1.4.3'
+    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/api_docs.rb

@@ -0,0 +1,99 @@
+require "sinatra/base"
+
+module Sinatra
+  module APIDocs
+    VERSION = "0.1.1"
+
+    def self.route_added(verb, path, proc)
+      return if verb == "HEAD"
+
+      reset_documentation unless defined?(@@api_docs_sections)
+
+      return if @@api_docs_description == ""
+
+      @@api_docs ||= []
+      @@api_docs  << {
+        :url         => "#{verb} #{path}",
+        :section     => @@api_docs_section,
+        :description => @@api_docs_description,
+        :params      => @@api_docs_params,
+        :request     => @@api_docs_request,
+        :response    => @@api_docs_response
+      }
+
+      @@api_docs_description = nil
+      @@api_docs_params      = []
+      @@api_docs_request     = nil
+      @@api_docs_response    = nil
+    end
+
+    def self.reset_documentation
+      @@api_docs_sections    = []
+      @@api_docs_section     = ""
+      @@api_docs_description = ""
+      @@api_docs_params      = []
+      @@api_docs_request     = ""
+      @@api_docs_response    = ""
+    end
+
+    def reset_documentation
+      @@api_docs_sections    = []
+      @@api_docs_section     = ""
+      @@api_docs_description = ""
+      @@api_docs_params      = []
+      @@api_docs_request     = ""
+      @@api_docs_response    = ""
+    end
+
+    def documentation
+      @@api_docs
+    end
+
+    def sections
+      @@api_docs_sections
+    end
+
+    def section(name=nil)
+      if name then
+        @@api_docs_section    = name
+        @@api_docs_sections ||= []
+        @@api_docs_sections  << name
+      end
+
+      @@api_docs_section
+    end
+
+    def desc(description=nil)
+      @@api_docs_description = description if description
+      @@api_docs_description
+    end
+
+    def param(name, desc=nil)
+      @@api_docs_params ||= []
+      @@api_docs_params  << [name, desc] if desc
+      @@api_docs_params.detect { |d| d.first == name }.last
+    end
+
+    def request(body=nil)
+      @@api_docs_request = strip_left(body) if body
+      @@api_docs_request
+    end
+
+    def response(body=nil)
+      @@api_docs_response = strip_left(body) if body
+      @@api_docs_response
+    end
+
+    def strip_left(code)
+      first_line = code.split("\n").first
+      num_spaces = first_line.match(/\A */)[0].length
+      code.split("\n").map do |line|
+        line[num_spaces..-1]
+      end.join("\n")
+    end
+
+    extend self
+  end
+
+  register APIDocs
+end

data/lib/sinatra/api_docs/viewer.rb

@@ -0,0 +1,109 @@
+require "haml"
+require "json/pure"
+require "sinatra/api_docs"
+require "sinatra/base"
+
+class Sinatra::APIDocs::Viewer < Sinatra::Base
+
+  register Sinatra::APIDocs
+
+  def initialize(api_klass)
+    self.class.set :api_klass, api_klass
+    self.class.set :version,   api_klass.name.to_s.split("::").last.downcase
+    self.class.set :public,    File.expand_path("../public", __FILE__)
+    self.class.set :views,     File.expand_path("../views", __FILE__)
+    super()
+  end
+
+  helpers do
+    def code(code)
+      Haml::Filters::Preserve.render(Haml::Filters::Escaped.render(code))
+    end
+
+    def doc(page, title)
+      active = (env["PATH_INFO"] == "/#{page}") ? "active" : ""
+      %{ <li class="#{active}"><a href="/#{page}">#{title}</a></li> }
+    end
+
+    def docs
+      settings.api_klass.documentation
+    end
+
+    def docs_by_section(section)
+      docs.select { |doc| titleify(doc[:section]) == titleify(section) }
+    end
+
+    def render_docs(docs)
+      haml :page, :locals => { :docs => docs, :sections => sections }
+    end
+
+    def sections
+      settings.api_klass.sections
+    end
+
+    def titleify(name)
+      name.downcase.gsub(' ', '_')
+    end
+  end
+
+  section "API"
+
+  desc "API documentation in JSON format"
+
+  param "section", "Only return documentation for a particular section"
+
+  request "GET /docs.json"
+  response <<-RESPONSE
+    [
+      {
+        "section":"API",
+        "url":"GET /docs.json",
+        "params":[],
+        "request":"GET /docs.json",
+        "response":"response_example",
+        "description":"API documentation in JSON format"
+      }
+    ]
+  RESPONSE
+
+  get "/docs.json" do
+    if params[:section] then
+      docs_by_section(params[:section]).to_json
+    else
+      docs.to_json
+    end
+  end
+
+  get "/assets/stylesheets.css" do
+    content_type "text/css"
+    sass :documentation
+  end
+
+  get "/assets/scripts.js" do
+    content_type "text/javascript"
+    File.read("#{settings.views}/documentation.js")
+  end
+
+  get "/" do
+    render_docs docs_by_section(nil)
+  end
+
+  get "/:section" do |section|
+    render_docs docs_by_section(section)
+  end
+
+private ######################################################################
+
+  def markdown(template)
+    RDiscount.new(File.read("#{settings.views}/#{template}.md")).to_html
+  end
+
+end
+
+module Haml::Filters::Code
+  include Haml::Filters::Base
+
+  def render(text)
+    Haml::Filters::Preserve.render(Haml::Filters::Escaped.render(text))
+  end
+end

data/lib/sinatra/api_docs/views/documentation.sass

@@ -0,0 +1,142 @@
+*
+  :font-family Helvetica, Arial, sans-serif
+
+=code_title
+  :display block
+  :padding 6px 10px
+  :font-weight bold
+  :background #999
+  :color #333
+  :border-bottom 1px #000 solid
+  :margin-left -12px
+  :margin-right -12px
+  :margin-top -12px
+  :margin-bottom 12px
+
+.api
+  :padding-bottom 24px
+  :border-bottom 1px #666 dashed
+  :margin-bottom 24px
+
+  .url
+    :padding 6px 10px
+    :font-size 24px
+    :background #555
+    :color #eee
+    :font-weight bold
+    :border 1px #333 solid
+    :font-family Monaco, monospace
+
+  .description
+    :padding 12px
+
+  code
+    :font-family Monaco, monospace
+    :white-space pre
+    :background #ccc
+    :border 1px #333 solid
+    :padding 12px
+    :display block
+
+  .params
+    :margin-bottom 10px
+    :background #ccc
+    :border 1px #333 solid
+    :padding 12px
+    :display block
+    &:before
+      +code_title
+      :content "Parameters"
+    .param
+      :line-height 30px
+      .name
+        :display inline
+        :font-weight bold
+      .description
+        :display inline
+
+  .request
+    :margin-bottom 10px
+    &:before
+      +code_title
+      :content "Request"
+
+  .response
+    &:before
+      +code_title
+      :content "Response"
+
+body
+  :margin 0
+
+header
+  :background-color #333
+  :color #ccc
+  :padding 8px 16px
+
+  a
+    :color #ccf
+    :margin-left 10px
+
+  .title
+    :font-size 30px
+    :font-weight bold
+    :display inline
+
+  .version, .format, .search
+    :float right
+    :margin-top 8px
+    :margin-left 30px
+    
+  .version
+    .number
+      :display inline
+      :font-weight bold
+
+  .search
+    :margin-left 60px
+    #search
+      :font-size 18px
+      :margin-left 6px
+      :margin-top -4px
+      :width 200px
+      
+#toc
+  :position absolute
+  :top 51px
+  :bottom 0px
+  :left 0px
+  :float left
+  :width 300px
+  :background eee
+  :padding 0
+  :padding-top 0px
+  :margin 0
+  :background #999
+  li.title
+    :background #aaa
+    :color #333
+  li
+    :background #ccc
+    :color #333
+    :font-weight bold
+    :font-size 20px
+    :list-style-type none
+    :border 1px #999 solid    
+    :border-right 2px #999 solid
+    :padding 10px
+    &.active
+      :background #fff
+      :border-right 0
+    a
+      :color #333
+      :font-weight bold
+    
+#content
+  :position absolute
+  :left 301px
+  :top 51px
+  :right 0px
+  :bottom 0px
+  :overflow auto
+  :padding 20px

data/lib/sinatra/api_docs/views/layout.haml

@@ -0,0 +1,27 @@
+!!! 5
+
+%html
+
+  %head
+    %title Heroku API Documentation
+    %link{ :rel => "stylesheet", :href => "/assets/stylesheets.css" }
+    %script{ :type => "text/javascript", :src => "/assets/scripts.js" }
+
+  %body
+    %header
+      .title
+        Heroku API Documentation
+      / .search
+      /   Search
+      /   %input#search{ :type => "text" }
+      / .format
+      /   %a{ :format => "json", :href => "javascript:void(0);" } JSON
+      /   %a{ :format => "xml",  :href => "javascript:void(0);" } XML
+      .version
+        Version:
+        .number= settings.version.to_s[1..-1]
+
+    = haml :toc, :layout => false, :locals => { :sections => sections }
+
+    #content
+      = yield

data/lib/sinatra/api_docs/views/page.haml

@@ -0,0 +1,22 @@
+- docs.each do |doc|
+
+  .api
+
+    .url
+      = doc[:url]
+
+    .description
+      = doc[:description]
+
+    - if doc[:params].length > 0
+      .params
+        - doc[:params].each do |name, description|
+          .param
+            .name= name
+            .description= description
+
+    %code.request
+      = code doc[:request]
+
+    %code.response
+      = code doc[:response]

data/lib/sinatra/api_docs/views/toc.haml

@@ -0,0 +1,3 @@
+%ul#toc
+  - sections.each do |section|
+    = doc titleify(section), section

data/spec/sinatra/api_docs_spec.rb

@@ -0,0 +1,59 @@
+require "spec_helper"
+require "sinatra/api_docs"
+require "sinatra/base"
+
+class MockSinatraApp < Sinatra::Base
+  register Sinatra::APIDocs
+end
+
+describe Sinatra::APIDocs do
+  let(:app) { Class.new(MockSinatraApp) }
+
+  before(:each) { app.reset_documentation }
+
+  it "can add a section" do
+    app.section "test_section"
+    app.section.should == "test_section"
+  end
+
+  it "can set a description" do
+    app.desc "test_description"
+    app.desc.should == "test_description"
+  end
+
+  it "can set params" do
+    app.param "test_param", "test_param_value"
+    app.param("test_param").should == "test_param_value"
+  end
+
+  it "can set a request body" do
+    app.request "test_request"
+    app.request.should == "test_request"
+  end
+
+  it "can set a response body" do
+    app.response "test_response"
+    app.response.should == "test_response"
+  end
+
+  it "can define documentation" do
+    app.section  "test_section"
+    app.desc     "test_description"
+    app.param    "test_param", "test_param_value"
+    app.request  "test_request"
+    app.response "test_response"
+    app.get("/") do
+      "root"
+    end
+
+    app.documentation.should == [{
+      :url         => "GET /", 
+      :section     => "test_section", 
+      :description => "test_description", 
+      :params      => [["test_param", "test_param_value"]],
+      :request     => "test_request", 
+      :response    => "test_response"
+    }]
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require "rubygems"
+require "rspec"
+
+$:.unshift "lib"
+
+Rspec.configure do |config|
+  config.color_enabled = true
+end

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification 
+name: sinatra-api-docs
+version: !ruby/object:Gem::Version 
+  hash: 25
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 1
+  version: 0.1.1
+platform: ruby
+authors: 
+- David Dollar
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-06-29 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id001 !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: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !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: *id002
+- !ruby/object:Gem::Dependency 
+  name: haml
+  prerelease: false
+  requirement: &id003 !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: *id003
+- !ruby/object:Gem::Dependency 
+  name: json_pure
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 1
+        segments: 
+        - 1
+        - 4
+        - 3
+        version: 1.4.3
+  type: :runtime
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: sinatra
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 1
+        - 0
+        version: "1.0"
+  type: :runtime
+  version_requirements: *id005
+description: Create documentation for an API built in Sinatra.
+email: ddollar@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- Rakefile
+- lib/sinatra/api_docs.rb
+- lib/sinatra/api_docs/viewer.rb
+- lib/sinatra/api_docs/views/documentation.sass
+- lib/sinatra/api_docs/views/layout.haml
+- lib/sinatra/api_docs/views/page.haml
+- lib/sinatra/api_docs/views/toc.haml
+- spec/sinatra/api_docs_spec.rb
+- spec/spec_helper.rb
+has_rdoc: false
+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/api_docs_spec.rb
+- spec/spec_helper.rb