fdoc 0.2.6 → 0.2.7

data/README.md

@@ -2,9 +2,9 @@
 
 High-quality documentation is extremely useful, but maintaining it is often a pain. We aim to create a tool to facilitate easy creation and maintenance of API documentation.
 
-In a Rails app, fdoc can help document an API as well as verify that requests and responses adhere to their appropriate schemata.
+In a Rails or Sinatra app, fdoc can help document an API as well as verify that requests and responses adhere to their appropriate schemata.
 
-Outside a Rails app, fdoc can provide a common format for API documentation, as well as the ability to generate basic HTML pages for humans to consume.
+Outside a Rails or Sinatra app, fdoc can provide a common format for API documentation, as well as the ability to generate basic HTML pages for humans to consume.
 
 fdoc is short for Farnsdocs. They are named for everybody's favorite, good news-bearing, crotchety old man, Professor Farnsworth.
 
@@ -51,6 +51,35 @@ fdoc also has a scaffolding mode, where it attemps to infer the schema of a requ
 
 For more information on scaffolding, please see the more in-depth [fdoc scaffolding example][github_scaffold].
 
+### In a Sinatra app
+
+Add fdoc to your Gemfile.
+
+    gem 'fdoc'
+
+Tell fdoc where to look for `.fdoc` files. By default, fdoc will look in `docs/fdoc`, but you can change this behavior to look anywhere. This fits best in something like a spec\_helper file.
+
+```ruby
+require 'fdoc'
+
+Fdoc.service_path = "path/to/your/fdocs"
+```
+
+fdoc is built to work around your Sinatra app specs in rspec, and provides `Fdoc::SpecWatcher` as a mixin. Make sure to include it *inside* your top level describe.
+
+```ruby
+require 'fdoc/spec_watcher'
+
+describe Sinatra::Appllication do
+  include Rack::Test::Methods
+  include Fdoc::SpecWatcher
+
+  def app
+    Sinatra::Application
+  end
+end
+```
+
 ### Outside a Rails App
 
 fdoc provides the `fdoc_to_html` script to transform a directory of `.fdoc` files into more human-readable HTML.

data/lib/fdoc/presenters/html_presenter.rb

@@ -1,5 +1,6 @@
 require 'erb'
 require 'kramdown'
+require 'json'
 
 # HtmlPresenters assist in generating Html for fdoc classes.
 # HtmlPresenters is an abstract class with a lot of helper methods

data/lib/fdoc/spec_watcher.rb

@@ -31,15 +31,23 @@ module Fdoc
           opts[:fdoc]
         end
 
+        real_response = if respond_to? :response
+          # we are on rails
+          response
+        else
+          # we are on sinatra
+          last_response
+        end
+
         if path
           response_params = begin
-            JSON.parse(response.body)
+            JSON.parse(real_response.body)
           rescue
             {}
           end
-          successful = Fdoc.decide_success(response_params, response.status)
+          successful = Fdoc.decide_success(response_params, real_response.status)
           Service.verify!(verb, path, request_params, response_params,
-            response.status, successful)
+            real_response.status, successful)
         end
 
         result

data/spec/fdoc/spec_watcher_spec.rb

@@ -3,36 +3,75 @@ require 'spec_helper'
 require 'fdoc/spec_watcher'
 
 describe Fdoc::SpecWatcher do
-  before do
-    # This should be an integration test, but for now a smoke test suffices to
-    # surface obvious bugs and verify some behaviours.
-    @klass = Class.new do
-      def example
-        Struct.new(:metadata).new(:fdoc => 'index')
-      end
 
-      def response
-        Struct.new(:body, :status).new("{}", 200)
+  context "on rails" do
+    before do
+      # This should be an integration test, but for now a smoke test suffices to
+      # surface obvious bugs and verify some behaviours.
+      @klass = Class.new do
+        def example
+          Struct.new(:metadata).new(:fdoc => 'index')
+        end
+
+        def response
+          Struct.new(:body, :status).new("{}", 200)
+        end
+
+        def get(action, params)
+          params
+        end
+      end.new
+      @klass.extend(Fdoc::SpecWatcher)
+    end
+
+    it 'should verify when params are a hash' do
+      Fdoc::Service.should_receive(:verify!).with do |*args|
+        args[2] == {:id => 1}
       end
+      @klass.get(:index, {:id => 1})
+    end
 
-      def get(action, params)
-        params
+    it 'should verify when params are JSON' do
+      Fdoc::Service.should_receive(:verify!).with do |*args|
+        args[2] == {'id' => 1}
       end
-    end.new
-    @klass.extend(Fdoc::SpecWatcher)
+      @klass.get(:index, {:id => 1}.to_json)
+    end
   end
 
-  it 'should verify when params are a hash' do
-    Fdoc::Service.should_receive(:verify!).with do |*args|
-      args[2] == {:id => 1}
+  context "on sinatra" do
+
+    before do
+      # This should be an integration test, but for now a smoke test suffices to
+      # surface obvious bugs and verify some behaviours.
+      @klass = Class.new do
+        def example
+          Struct.new(:metadata).new(:fdoc => 'index')
+        end
+
+        def last_response
+          Struct.new(:body, :status).new("{}", 200)
+        end
+
+        def get(action, params)
+          params
+        end
+      end.new
+      @klass.extend(Fdoc::SpecWatcher)
     end
-    @klass.get(:index, {:id => 1})
-  end
 
-  it 'should verify when params are JSON' do
-    Fdoc::Service.should_receive(:verify!).with do |*args|
-      args[2] == {'id' => 1}
+    it 'should verify when params are a hash' do
+      Fdoc::Service.should_receive(:verify!).with do |*args|
+        args[2] == {:id => 1}
+      end
+      @klass.get("/", {:id => 1})
+    end
+
+    it 'should verify when params are JSON' do
+      Fdoc::Service.should_receive(:verify!).with do |*args|
+        args[2] == {'id' => 1}
+      end
+      @klass.get("/", {:id => 1}.to_json)
     end
-    @klass.get(:index, {:id => 1}.to_json)
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fdoc
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.7
   prerelease: 
 platform: ruby
 authors:
@@ -15,7 +15,7 @@ date: 2011-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &70196446801520 !ruby/object:Gem::Requirement
+  requirement: &70224688026140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -23,10 +23,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70196446801520
+  version_requirements: *70224688026140
 - !ruby/object:Gem::Dependency
   name: json-schema
-  requirement: &70196446800760 !ruby/object:Gem::Requirement
+  requirement: &70224688025480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -34,10 +34,10 @@ dependencies:
         version: 1.0.1
   type: :runtime
   prerelease: false
-  version_requirements: *70196446800760
+  version_requirements: *70224688025480
 - !ruby/object:Gem::Dependency
   name: kramdown
-  requirement: &70196446800080 !ruby/object:Gem::Requirement
+  requirement: &70224688024780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -45,10 +45,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70196446800080
+  version_requirements: *70224688024780
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70196446799580 !ruby/object:Gem::Requirement
+  requirement: &70224688023900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -56,10 +56,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70196446799580
+  version_requirements: *70224688023900
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70196446799040 !ruby/object:Gem::Requirement
+  requirement: &70224688023100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -67,10 +67,10 @@ dependencies:
         version: '2.5'
   type: :development
   prerelease: false
-  version_requirements: *70196446799040
+  version_requirements: *70224688023100
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &70196446798560 !ruby/object:Gem::Requirement
+  requirement: &70224688022600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -78,10 +78,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70196446798560
+  version_requirements: *70224688022600
 - !ruby/object:Gem::Dependency
   name: cane
-  requirement: &70196446798060 !ruby/object:Gem::Requirement
+  requirement: &70224688022020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -89,7 +89,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70196446798060
+  version_requirements: *70224688022020
 description: A tool for documenting API endpoints.
 email: support@squareup.com
 executables: