RubyGems - useless-doc - Versions diffs - 0.2.2 → 0.2.3 - Mend

useless-doc 0.2.2 → 0.2.3

Files changed (12) hide show

data/lib/useless/doc/rack/transform.rb +8 -2
data/lib/useless/doc/ui/godel.rb +43 -10
data/lib/useless/doc/ui/godel/api.mustache +38 -0
data/lib/useless/doc/ui/godel/{template.mustache → resource.mustache} +0 -0
data/lib/useless/doc/version.rb +1 -1
data/spec/documents/api.json +16 -1
data/spec/useless/doc/rack/application_spec.rb +11 -1
data/spec/useless/doc/rack/transform_spec.rb +18 -5
data/spec/useless/doc/ui/godel_spec.rb +125 -0
data/useless-doc.gemspec +1 -0
metadata +22 -4
data/lib/useless/doc/ui.rb +0 -37

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

@@ -24,8 +24,14 @@ module Useless
           if response[0] == 200
             begin
-              resource = Serialization::Load.resource(response[2].first)
-              html = env['useless.doc.ui'].html(resource)
+              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.']]

data/lib/useless/doc/ui/godel.rb CHANGED Viewed

@@ -1,29 +1,55 @@
 require 'mustache'
 require 'forwardable'
-require 'useless/doc/ui'
 module Useless
   module Doc
     module UI
-      class Godel < ::Mustache
-        include UI
+      class Godel
+        def self.api(api)
+          API.new(api).render
+        end
+        def self.resource(resource)
+          Resource.new(resource).render
+        end
+        def self.css
+          File.read(asset_path + '/stylesheet.css')
+        end
-        def initialize(resource)
-          @resource = Godel::Resource.new(resource)
+        def self.asset_path
+          File.dirname(__FILE__) + '/godel'
         end
-        class Resource
+        class API < Mustache
+          extend Forwardable
+          def_delegators :@api, :url, :description
+          self.template_file = Godel.asset_path + '/api.mustache'
+          def initialize(api)
+            @api = api
+          end
+          def resources
+            @api.resources.map{ |resource| Godel::Resource.new(resource) }
+          end
+        end
+        class Resource < Mustache
           extend Forwardable
           def_delegators :@resource, :path, :description
+          self.template_file = Godel.asset_path + '/resource.mustache'
           def initialize(resource)
             @resource = resource
           end
           def requests
-            @resource.requests.map{ |request| Godel::Request.new(request) }
+            @resource.requests.map{ |request| Godel::Request.new(request, self) }
           end
         end
@@ -32,14 +58,15 @@ module Useless
           def_delegators :@request, :method, :description, :parameters, :headers, :body
-          def initialize(request)
+          def initialize(request, resource)
             @request = request
+            @resource = resource
           end
           def authentication_requirement
             @request.authentication_required ?
               'Authentication Required' :
-              'Authenication Not Required'
+              'Authentication Not Required'
           end
           def parameters?
@@ -53,6 +80,12 @@ module Useless
           def responses
             @request.responses.map { |response| Godel::Response.new(response) }
           end
+          def doc_path
+            if @resource
+              "#{@resource.path}##{method}"
+            end
+          end
         end
         class Response

data/lib/useless/doc/ui/godel/api.mustache ADDED Viewed

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>{{url}} | doc.useless.io</title>
+  <link href="/doc.css" media="screen" rel="stylesheet" type="text/css" />
+</head>
+<body>
+  <h1>{{url}}</h1>
+  <p>{{description}}</p>
+  {{#resources}}
+    <section>
+      <h2>{{path}}</h2>
+      <p>{{description}}</p>
+      <table>
+        <th>
+          <tr>
+            <td>Method</td>
+            <td>Description</td>
+          <tr>
+        </th>
+        <tbody>
+          {{#requests}}
+            <tr>
+              <td><a href="{{doc_path}}">{{method}}</a></td>
+              <td>{{description}}</td>
+            </tr>
+          {{/requests}}
+        </tbody>
+      </table>
+    </section>
+  {{/resources}}
+</body>

data/lib/useless/doc/ui/godel/{template.mustache → resource.mustache} RENAMED Viewed

File without changes

data/lib/useless/doc/version.rb CHANGED Viewed

@@ -1,5 +1,5 @@
 module Useless
   module Doc
-    VERSION = '0.2.2'
+    VERSION = '0.2.3'
   end
 end

data/spec/documents/api.json CHANGED Viewed

@@ -5,7 +5,22 @@
     {
       "path": "/twonks/:id",
       "description": "The most critical aspect.",
-      "requests": []
+      "requests": [
+        {
+          "method": "GET",
+          "description": "Get dat twonk."
+        }
+      ]
+    },
+    {
+      "path": "/twonks/:id/werp",
+      "description": "That other shit.",
+      "requests": [
+        {
+          "method": "POST",
+          "description": "Make dem werps."
+        }
+      ]
     }
   ]
 }

data/spec/useless/doc/rack/application_spec.rb CHANGED Viewed

@@ -25,7 +25,17 @@ describe Useless::Doc::Rack::Application do
     last_response.should be_not_found
   end
-  it 'should return HTML if proper JSON is retrieved' do
+  it 'should return API HTML if proper JSON is retrieved' do
+    Useless::Doc::Rack::Retriever::Stub.should_receive(:retrieve).
+      with('http://some-api.useless.io/').
+      and_return(load_document('api.json'))
+    get 'http://some-api.doc.useless.io/'
+    last_response.should be_ok
+    last_response.body.should =~ /<h1>twonk\.useless\.io<\/h1>/
+  end
+  it 'should return resource HTML if proper JSON is retrieved' do
     Useless::Doc::Rack::Retriever::Stub.should_receive(:retrieve).
       with('http://some-api.useless.io/some/resource').
       and_return(load_document('twonk.json'))

data/spec/useless/doc/rack/transform_spec.rb CHANGED Viewed

@@ -1,11 +1,18 @@
 require File.dirname(__FILE__) + '/../../../spec_helper'
+require 'rack'
 require 'useless/doc/rack/transform'
 require 'useless/doc/ui/godel'
 describe Useless::Doc::Rack::Transform do
-  def good_base
-    @good_base ||= lambda do |env|
+  def api_base
+    @api_base ||= lambda do |env|
+      [200, {'Content-Type' => 'application/json'}, [load_document('api.json')]]
+    end
+  end
+  def resource_base
+    @resource_base ||= lambda do |env|
       [200, {'Content-Type' => 'application/json'}, [load_document('twonk.json')]]
     end
   end
@@ -18,7 +25,7 @@ describe Useless::Doc::Rack::Transform do
   end
   it 'should raise an error if a UI is not specified' do
-    app = Useless::Doc::Rack::Transform.new(good_base)
+    app = Useless::Doc::Rack::Transform.new(resource_base)
     request = Rack::MockRequest.new(app)
     lambda { request.get('http://some-api.doc.granmal.com/some/resource') }.should raise_error(RuntimeError, 'No UI specified.')
   end
@@ -36,8 +43,14 @@ describe Useless::Doc::Rack::Transform do
     response.body.should == 'Not Found.'
   end
-  it 'should transform the JSON returned by the downstream app to HTML' do
-    response = Rack::MockRequest.new(app(good_base)).get('http://some-api.doc.granmal.com/some/resource')
+  it 'should transform the API JSON returned by the downstream app to HTML, if the request path is root' do
+    response = Rack::MockRequest.new(app(api_base)).get('http://twonk.useless.io/')
+    response['Content-Type'].should == 'text/html'
+    response.body.should =~ /<h1>twonk\.useless\.io<\/h1>/
+  end
+  it 'should transform the resource JSON returned by the downstream app to HTML' do
+    response = Rack::MockRequest.new(app(resource_base)).get('http://some-api.doc.granmal.com/some/resource')
     response['Content-Type'].should == 'text/html'
     response.body.should =~ /<h1>\/twonks\/:id<\/h1>/
   end

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

@@ -0,0 +1,125 @@
+require File.dirname(__FILE__) + '/../../../spec_helper'
+require 'nokogiri'
+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
+    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 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 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 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 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.'
+      as.find { |a| a.content == 'POST' }['href'].should == '/twonks/:id/werp#POST'
+      td_content.should include 'Make dem werps.'
+    end
+  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 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', '200', '201'])
+    end
+    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('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'
+    end
+  end
+end

data/useless-doc.gemspec CHANGED Viewed

@@ -23,4 +23,5 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'rspec'
   gem.add_development_dependency 'rack-test'
+  gem.add_development_dependency 'nokogiri'
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: useless-doc
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
   prerelease:
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-01-15 00:00:00.000000000 Z
+date: 2013-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -139,6 +139,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: For parsing and serving Useless documentation.
 email: khy@me.com
 executables: []
@@ -168,10 +184,10 @@ files:
 - 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/resource.mustache
 - lib/useless/doc/ui/godel/stylesheet.css
-- lib/useless/doc/ui/godel/template.mustache
 - lib/useless/doc/version.rb
 - spec/documents/api.json
 - spec/documents/twonk.json
@@ -186,6 +202,7 @@ files:
 - spec/useless/doc/serialization/dump_spec.rb
 - spec/useless/doc/serialization/load_spec.rb
 - spec/useless/doc/sinatra_spec.rb
+- spec/useless/doc/ui/godel_spec.rb
 - useless-doc.gemspec
 homepage:
 licenses: []
@@ -225,3 +242,4 @@ test_files:
 - spec/useless/doc/serialization/dump_spec.rb
 - spec/useless/doc/serialization/load_spec.rb
 - spec/useless/doc/sinatra_spec.rb
+- spec/useless/doc/ui/godel_spec.rb

data/lib/useless/doc/ui.rb DELETED Viewed

@@ -1,37 +0,0 @@
-require 'forwardable'
-require 'mustache'
-module Useless
-  module Doc
-    module UI
-      def self.included(base)
-        base.instance_eval do
-          extend ClassMethods
-          self.template_file = dir + 'template.mustache'
-          extend Forwardable
-          def_delegators :@resource, :path, :description, :requests
-        end
-      end
-      module ClassMethods
-        def html(resource)
-          new(resource).render
-        end
-        def css
-          File.read(dir + 'stylesheet.css')
-        end
-        def dir
-          key = Mustache.underscore(name.split('::').last)
-          File.dirname(__FILE__) + "/ui/#{key}/"
-        end
-      end
-      def initialize(resource)
-        @resource = resource
-      end
-    end
-  end
-end