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

useless-doc 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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