useless-doc 0.2.3 → 0.3.0

data/spec/useless/doc/ui/godel_spec.rb

@@ -1,125 +1,165 @@
 require File.dirname(__FILE__) + '/../../../spec_helper'
 
 require 'nokogiri'
+require 'useless/doc'
+require 'useless/doc/router'
 require 'useless/doc/ui/godel'
-require 'useless/doc/serialization/load'
 
 describe Useless::Doc::UI::Godel do
-  describe '.resource' do
-    before(:each) do
-      json = load_document('api.json').read
-      api = Useless::Doc::Serialization::Load.api json
-      result = Useless::Doc::UI::Godel.api(api)
-      @doc = Nokogiri::HTML(result)
-    end
+  describe '.html' do
+    context 'for a Core::Domain instance' do
+      before(:all) do
+        router = Useless::Doc::Router.default
+        json = load_document('domain.json').read
+        domain = Useless::Doc.load.domain(json)
+        result = Useless::Doc::UI::Godel.new(router).html(domain)
+        @doc = Nokogiri::HTML(result)
+      end
 
-    it 'should render the URL in the only h1' do
-      h1s = @doc.css('h1')
-      h1s.length.should == 1
-      h1s.first.content.should == 'twonk.useless.io'
-    end
+      it 'should render the name in the only h1' do
+        h1s = @doc.css('h1')
+        h1s.length.should == 1
+        h1s.first.content.should == 'Useless'
+      end
 
-    it 'should render the API description in a top-level p' do
-      description = @doc.css('body > p')
-      description.length.should == 1
-      description.first.content.should == 'Twonk information. Duh.'
-    end
+      it 'should render the domain description in an article p' do
+        description = @doc.css('article p.description.domain')
+        description.length.should == 1
+        description.first.content.should == 'A collection of useless APIs.'
+      end
 
-    it 'should render resouce paths as h2s' do
-      h2s = @doc.css('h2')
-      h2s.length.should == 2
-      h2s.map { |h2| h2.content }.should match_array(['/twonks/:id', '/twonks/:id/werp'])
-    end
+      it 'should render API names as a\'s, with correct doc URLs' do
+        as = @doc.css('a.name')
+        as.length.should == 2
+        as.map { |a| a.content }.should match_array(['The Jah API', 'The Twonk API'])
+        as.map { |a| a['href'] }.should match_array(['http://jah.doc.useless.io', 'http://twonk.doc.useless.io'])
+      end
 
-    it 'should render resouce descriptions as ps within the section' do
-      ps = @doc.css('section > p')
-      ps.length.should == 2
-      ps.map { |h2| h2.content }.should match_array(['The most critical aspect.', 'That other shit.'])
+      it 'should render API descriptions as ps within the section' do
+        ps = @doc.css('section > p')
+        ps.length.should == 2
+        ps.map { |h2| h2.content }.should match_array(['Jah, jah, jah.', 'TWONK!!!'])
+      end
     end
 
-    it 'should add a link for each method, with an appropriate description' do
-      as = @doc.css('table td a')
-      td_content = @doc.css('table td').map { |td| td.content }
-      as.find { |a| a.content == 'GET' }['href'].should == '/twonks/:id#GET'
-      td_content.should include 'Get dat twonk.'
+    context 'for a Core::API instance' do
+      before(:all) do
+        json = load_document('api.json').read
+        router = Useless::Doc::Router.default
+        api = Useless::Doc.load.api(json)
+        result = Useless::Doc::UI::Godel.new(router).html(api)
+        @doc = Nokogiri::HTML(result)
+      end
 
-      as.find { |a| a.content == 'POST' }['href'].should == '/twonks/:id/werp#POST'
-      td_content.should include 'Make dem werps.'
-    end
-  end
+      it 'should render the URL in the only h1' do
+        h1s = @doc.css('h1')
+        h1s.length.should == 1
+        h1s.first.content.should == 'Twonk API'
+      end
 
-  describe '.resource' do
-    before(:each) do
-      json = load_document('twonk.json').read
-      resource = Useless::Doc::Serialization::Load.resource json
-      result = Useless::Doc::UI::Godel.resource(resource)
-      @doc = Nokogiri::HTML(result)
-    end
+      it 'should render the API description in an article p' do
+        description = @doc.css('article p.description.api')
+        description.length.should == 1
+        description.first.content.should == 'Twonk information. Duh.'
+      end
 
-    it 'should render the path within the only h1' do
-      h1s = @doc.css('h1')
-      h1s.length.should == 1
-      h1s.first.content.should == '/twonks/:id'
-    end
+      it 'should render resouce paths as a\'s' do
+        as = @doc.css('a.path')
+        as.length.should == 2
+        as.map { |a| a.content }.should match_array(['/twonks/:id', '/twonks/:id/werp'])
+      end
 
-    it 'should render the methods as h2s' do
-      h2s = @doc.css('h2')
-      h2s.length.should == 2
-      h2s.map { |h2| h2.content }.should match_array(['GET', 'PUT'])
-    end
+      it 'should render resouce descriptions as ps within the section' do
+        ps = @doc.css('section > p')
+        ps.length.should == 2
+        ps.map { |h2| h2.content }.should match_array(['The most critical aspect.', 'That other shit.'])
+      end
 
-    it 'should render response codes as h3s' do
-      h3s = @doc.css('h3')
-      h3s.length.should == 3
-      h3s.map { |h3| h3.content }.should match_array(['404', '200', '201'])
-    end
+      it 'should add a link for each method, with an appropriate description' do
+        as = @doc.css('table td a')
+        td_content = @doc.css('table td').map { |td| td.content }
+        as.find { |a| a.content == 'GET' }['href'].should == '/twonks/:id#GET'
+        td_content.should include 'Get dat twonk.'
 
-    it 'should contain the method and response code descriptions in ps' do
-      p_content = @doc.css('p').map { |p| p.content }
-      p_content.should include 'The most critical aspect.'
-      p_content.should include 'Retrieve a representation of an individual twonk.'
-      p_content.should include 'A twonk with the specified ID could not be found.'
-      p_content.should include 'The specified twonk was retrieved successfully.'
-      p_content.should include 'The specified twonk was updated successfully.'
+        as.find { |a| a.content == 'POST' }['href'].should == '/twonks/:id/werp#POST'
+        td_content.should include 'Make dem werps.'
+      end
     end
 
-    it 'should add parameter information to a table' do
-      [
-        { key: 'id', description: 'The ID of the desired twonk.' },
-        { key: 'werp', description: 'Self-explanatory.' },
-        { key: 'id', description: 'The ID of the twonk to be updated.' }
-      ].each do |param|
-        @doc.css('table').find do |table|
-          table.content.match(param[:key]) and
-          table.content.match(param[:description])
-        end.should_not be_nil
+    context 'for a Core::Resource instance' do
+      before(:each) do
+        json = load_document('twonk.json').read
+        router = Useless::Doc::Router.default
+        resource = Useless::Doc.load.resource json
+        result = Useless::Doc::UI::Godel.new(router).html(resource)
+        @doc = Nokogiri::HTML(result)
+      end
+
+      it 'should render the path within the only h1' do
+        h1s = @doc.css('h1')
+        h1s.length.should == 1
+        h1s.first.content.should == '/twonks/:id'
+      end
+
+      it 'should render the methods as h2s' do
+        h2s = @doc.css('h2')
+        h2s.length.should == 2
+        h2s.map { |h2| h2.content }.should match_array(['GET', 'PUT'])
+      end
+
+      it 'should render response codes as h3s' do
+        h3s = @doc.css('h3')
+        h3s.length.should == 3
+        h3s.map { |h3| h3.content }.should match_array(['404 Not Found', '200 OK', '201 Created'])
       end
-    end
 
-    it 'should add body information to a table' do
-      [
-        { key: 'name', description: 'The name of the twonk.' },
-        { key: 'created_by', description: 'The short name of the user who created the twonk.' },
-        { key: 'hoinked_by', description: 'The ID of the person who hoinked this twonk.' }
-      ].each do |attribute|
+      it 'should contain the method and response code descriptions in ps' do
+        p_content = @doc.css('p').map { |p| p.content }
+        p_content.should include 'The most critical aspect.'
+        p_content.should include 'Retrieve a representation of an individual twonk.'
+        p_content.should include 'A twonk with the specified ID could not be found.'
+        p_content.should include 'The specified twonk was retrieved successfully.'
+        p_content.should include 'The specified twonk was updated successfully.'
+      end
+
+      it 'should add parameter information to a table' do
+        [
+          { key: 'id', description: 'The ID of the desired twonk.' },
+          { key: 'werp', description: 'Self-explanatory.' },
+          { key: 'id', description: 'The ID of the twonk to be updated.' }
+        ].each do |param|
+          @doc.css('table').find do |table|
+            table.content.match(param[:key]) and
+            table.content.match(param[:description])
+          end.should_not be_nil
+        end
+      end
+
+      it 'should add body information to a table' do
+        [
+          { key: 'name', description: 'The name of the twonk.' },
+          { key: 'created_by', description: 'The short name of the user who created the twonk.' },
+          { key: 'hoinked_by', description: 'The ID of the person who hoinked this twonk.' }
+        ].each do |attribute|
+          @doc.css('table').find do |table|
+            table.content.match(attribute[:key]) and
+            table.content.match(attribute[:description])
+          end.should_not be_nil
+        end
+      end
+
+      it 'should add header information to a table' do
         @doc.css('table').find do |table|
-          table.content.match(attribute[:key]) and
-          table.content.match(attribute[:description])
+          table.content.match('User-Agent') and
+          table.content.match('The thingy you\'re using.')
         end.should_not be_nil
       end
-    end
 
-    it 'should add header information to a table' do
-      @doc.css('table').find do |table|
-        table.content.match('User-Agent') and
-        table.content.match('The thingy you\'re using.')
-      end.should_not be_nil
-    end
-
-    it 'should include authentication information in lis' do
-      li_content = @doc.css('li').map { |li| li.content }
-      li_content.should include 'Authentication Required'
-      li_content.should include 'Authentication Not Required'
+      it 'should include authentication information in lis' do
+        li_content = @doc.css('li').map { |li| li.content }
+        li_content.should include 'Authentication Required'
+        li_content.should include 'Authentication Not Required'
+      end
     end
   end
 end

data/useless-doc.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |gem|
   gem.add_dependency 'oj'
   gem.add_dependency 'rack'
   gem.add_dependency 'typhoeus'
-  gem.add_dependency 'low'
+  gem.add_dependency 'low', '~> 0.0.15'
   gem.add_dependency 'sinatra'
   gem.add_dependency 'mustache'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: useless-doc
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-16 00:00:00.000000000 Z
+date: 2013-02-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -64,17 +64,17 @@ dependencies:
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.0.15
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.0.15
 - !ruby/object:Gem::Dependency
   name: sinatra
   requirement: !ruby/object:Gem::Requirement
@@ -168,37 +168,46 @@ files:
 - README.md
 - Rakefile
 - lib/useless/doc.rb
+- lib/useless/doc/client.rb
 - lib/useless/doc/core/api.rb
 - lib/useless/doc/core/body.rb
+- lib/useless/doc/core/domain.rb
 - lib/useless/doc/core/header.rb
 - lib/useless/doc/core/request.rb
 - lib/useless/doc/core/resource.rb
 - lib/useless/doc/core/response.rb
 - lib/useless/doc/dsl.rb
-- lib/useless/doc/rack/application.rb
-- lib/useless/doc/rack/proxy.rb
-- lib/useless/doc/rack/retriever.rb
-- lib/useless/doc/rack/stylesheet.rb
-- lib/useless/doc/rack/transform.rb
+- lib/useless/doc/rack.rb
+- lib/useless/doc/rack/css.rb
+- lib/useless/doc/rack/html.rb
+- lib/useless/doc/rack/subject.rb
 - lib/useless/doc/rack/ui.rb
+- lib/useless/doc/rack/url.rb
+- lib/useless/doc/router.rb
 - lib/useless/doc/serialization/dump.rb
 - lib/useless/doc/serialization/load.rb
 - lib/useless/doc/sinatra.rb
+- lib/useless/doc/ui.rb
 - lib/useless/doc/ui/godel.rb
 - lib/useless/doc/ui/godel/api.mustache
+- lib/useless/doc/ui/godel/domain.mustache
 - lib/useless/doc/ui/godel/resource.mustache
 - lib/useless/doc/ui/godel/stylesheet.css
 - lib/useless/doc/version.rb
+- spec/config.ru
 - spec/documents/api.json
+- spec/documents/domain.json
 - spec/documents/twonk.json
 - spec/spec_helper.rb
+- spec/useless/doc/client_spec.rb
 - spec/useless/doc/dsl_spec.rb
-- spec/useless/doc/rack/application_spec.rb
-- spec/useless/doc/rack/proxy_spec.rb
-- spec/useless/doc/rack/retriever_spec.rb
-- spec/useless/doc/rack/stylesheet_spec.rb
-- spec/useless/doc/rack/transform_spec.rb
+- spec/useless/doc/rack/css_spec.rb
+- spec/useless/doc/rack/html_spec.rb
+- spec/useless/doc/rack/subject_spec.rb
 - spec/useless/doc/rack/ui_spec.rb
+- spec/useless/doc/rack/url_spec.rb
+- spec/useless/doc/rack_spec.rb
+- spec/useless/doc/router_spec.rb
 - spec/useless/doc/serialization/dump_spec.rb
 - spec/useless/doc/serialization/load_spec.rb
 - spec/useless/doc/sinatra_spec.rb
@@ -229,16 +238,20 @@ signing_key:
 specification_version: 3
 summary: For parsing and serving Useless documentation.
 test_files:
+- spec/config.ru
 - spec/documents/api.json
+- spec/documents/domain.json
 - spec/documents/twonk.json
 - spec/spec_helper.rb
+- spec/useless/doc/client_spec.rb
 - spec/useless/doc/dsl_spec.rb
-- spec/useless/doc/rack/application_spec.rb
-- spec/useless/doc/rack/proxy_spec.rb
-- spec/useless/doc/rack/retriever_spec.rb
-- spec/useless/doc/rack/stylesheet_spec.rb
-- spec/useless/doc/rack/transform_spec.rb
+- spec/useless/doc/rack/css_spec.rb
+- spec/useless/doc/rack/html_spec.rb
+- spec/useless/doc/rack/subject_spec.rb
 - spec/useless/doc/rack/ui_spec.rb
+- spec/useless/doc/rack/url_spec.rb
+- spec/useless/doc/rack_spec.rb
+- spec/useless/doc/router_spec.rb
 - spec/useless/doc/serialization/dump_spec.rb
 - spec/useless/doc/serialization/load_spec.rb
 - spec/useless/doc/sinatra_spec.rb

data/lib/useless/doc/rack/application.rb

@@ -1,47 +0,0 @@
-require 'rack/builder'
-require 'rack/commonlogger'
-require 'rack/reloader'
-require 'low/rack/rack_errors'
-require 'low/rack/request_logger'
-
-require 'useless/doc/rack/proxy'
-require 'useless/doc/rack/retriever'
-require 'useless/doc/rack/stylesheet'
-require 'useless/doc/rack/transform'
-require 'useless/doc/rack/ui'
-
-module Useless
-  module Doc
-    module Rack
-      class Application
-        def initialize(*subdomains)
-          @subdomains = subdomains
-        end
-
-        def call(env)
-          app.call(env)
-        end
-
-        private
-
-        def app
-          @app ||= begin
-            subdomains = @subdomains
-
-            ::Rack::Builder.app do
-              use Low::Rack::RackErrors
-              use Low::Rack::RequestLogger
-              use ::Rack::CommonLogger
-              use Useless::Doc::Rack::UI
-              use Useless::Doc::Rack::Stylesheet
-              use Useless::Doc::Rack::Retriever
-              use Useless::Doc::Rack::Transform
-
-              run Useless::Doc::Rack::Proxy.new(subdomains)
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/useless/doc/rack/proxy.rb

@@ -1,62 +0,0 @@
-require 'uri'
-require 'rack/request'
-
-module Useless
-  module Doc
-    module Rack
-
-      # +Doc::Proxy+ is a Rack app that provides an HTML interface to Useless
-      # API documentation. It assumes that each API resource responds to INFO
-      # requests with documentation JSON that corresponds to the format
-      # specified by +Doc::Serialization::Load+.
-      #
-      # It proxies requests according to a simple convention. For example, a
-      # GET request to some-api.doc.useless.io/some/resource will result in an
-      # OPTIONS request to some-api.useless.io/some/resource.
-      #
-      # If there is no corresponding endpoint, the proxy will respond with a
-      # 404. If the requested subdomain is not in the list of supported
-      # subdomains specified at initialization, the proxy will also respond
-      # with a 404.
-      #
-      class Proxy
-
-        def initialize(subdomains)
-          @subdomains = subdomains
-        end
-
-        def self.transform_url(url)
-          uri = URI(url)
-          new_host = uri.host.gsub(/\.doc\./, '.')
-          "#{uri.scheme}://#{new_host}#{uri.path}"
-        end
-
-        def call(env)
-          unless env['useless.doc.retriever']
-            raise 'No retriever specified.'
-          end
-
-          request = ::Rack::Request.new(env)
-
-          if valid_subdomain?(request.url)
-            url = Proxy.transform_url(request.url)
-
-            if json = env['useless.doc.retriever'].retrieve(url)
-              [200, {'Content-Type' => 'application/json'}, [json]]
-            else
-              [404, {'Content-Type' => 'text/plain'}, ['Documentation JSON is missing.']]
-            end
-          else
-            [404, {'Content-Type' => 'text/plain'}, ['Unknown subdomain.']]
-          end
-        end
-
-        private
-
-        def valid_subdomain?(url)
-          @subdomains.include?(url[/((?:\w|\-)+)\.doc\./, 1])
-        end
-      end
-    end
-  end
-end

data/lib/useless/doc/rack/retriever.rb

@@ -1,68 +0,0 @@
-require 'time'
-require 'typhoeus'
-
-module Useless
-  module Doc
-    module Rack
-
-      # +Doc::Rack::Retriever+ sets an appropriate retriever for the current
-      # RACK_ENV. In production it uses the +Standard+ retriever which makes
-      # real HTTP calls. Elsewhere, it uses +Stub+ which servers corresponding
-      # files from the spec/documents directory.
-      #
-      class Retriever
-        def initialize(app)
-          @app = app
-        end
-
-        def call(env)
-          if ENV['RACK_ENV'] == 'production'
-            env['useless.doc.retriever'] = Standard
-          else
-            env['useless.doc.retriever'] = Stub
-          end
-
-          @app.call(env)
-        end
-
-        module Standard
-          NotModified = 304
-
-          @cache = {}
-
-          def self.retrieve(url)
-            headers = { 'Accept' => 'application/json' }
-
-            if @cache[url]
-              headers['If-Modified-Since'] = @cache[url].timestamp.httpdate()
-            end
-
-            response = Typhoeus.options url, headers: headers
-
-            unless response.response_code == NotModified
-              @cache[url] = CacheItem.new(response.response_body, Time.now)
-            end
-
-            @cache[url].response_body
-          end
-
-          class CacheItem
-            attr_accessor :response_body, :timestamp
-
-            def initialize(response_body, timestamp)
-              @response_body, @timestamp = response_body, timestamp
-            end
-          end
-        end
-
-        class Stub
-          def self.retrieve(url)
-            uri = URI(url)
-            path = File.dirname(__FILE__) + "/../../../../spec/documents#{uri.path}.json"
-            File.read(path)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/useless/doc/rack/transform.rb

@@ -1,46 +0,0 @@
-require 'useless/doc/serialization/load'
-
-module Useless
-  module Doc
-    module Rack
-
-      # +Doc::Rack::Transform+ takes the a JSON response and attempts to parse
-      # it via +Doc::Serialization::Load+ and render it as HTML via the UI
-      # specified by env['useless.doc.ui'].
-      #
-      # If the JSON cannot be parsed, the response will be a 502.
-      #
-      class Transform
-        def initialize(app)
-          @app = app
-        end
-
-        def call(env)
-          unless env['useless.doc.ui']
-            raise 'No UI specified.'
-          end
-
-          response = @app.call(env)
-
-          if response[0] == 200
-            begin
-              if env['PATH_INFO'] == '/'
-                api = Serialization::Load.api(response[2].first)
-                html = env['useless.doc.ui'].api(api)
-              else
-                resource = Serialization::Load.resource(response[2].first)
-                html = env['useless.doc.ui'].resource(resource)
-              end
-
-              [200, {'Content-Type' => 'text/html'}, [html]]
-            rescue Oj::ParseError
-              [502, {'Content-Type' => 'text/plain'}, ['Documentation JSON is malformed.']]
-            end
-          else
-            response
-          end
-        end
-      end
-    end
-  end
-end