useless-doc 0.3.1 → 0.4.0

data/lib/useless/doc/core/body.rb

@@ -20,7 +20,7 @@ module Useless
         #
         def initialize(attrs)
           @content_type = attrs[:content_type]
-          @attributes   = attrs[:attributes]
+          @attributes   = attrs[:attributes] || []
         end
 
         # Documentation for an attribute on an HTTP body.

data/lib/useless/doc/core/domain.rb

@@ -13,12 +13,15 @@ module Useless
       # @!attribute [r] description
       #   @return [String] a description of the domain.
       #
+      # @!attribute [r] timestamp
+      #   @return [Time] the time that this domain doc was last updated.
+      #
       # @!attribute [r] apis
       #   @return [Array<API>] the APIs included in this domain.
       #
       class Domain
 
-        attr_accessor :name, :url, :description, :apis
+        attr_accessor :name, :url, :description, :timestamp, :apis
 
         # @param [Hash] attrs corresponds to the class's instance attributes.
         #
@@ -26,7 +29,8 @@ module Useless
           @name = attrs[:name]
           @url = attrs[:url]
           @description = attrs[:description]
-          @apis = attrs[:apis]
+          @timestamp = attrs[:timestamp]
+          @apis = attrs[:apis] || []
         end
       end
     end

data/lib/useless/doc/core/request.rb

@@ -54,10 +54,10 @@ module Useless
           @method                   = attrs[:method]
           @description              = attrs[:description]
           @authentication_required  = attrs[:authentication_required]
-          @parameters               = attrs[:parameters]
-          @headers                  = attrs[:headers]
+          @parameters               = attrs[:parameters] || []
+          @headers                  = attrs[:headers] || []
           @body                     = attrs[:body]
-          @responses                = attrs[:responses]
+          @responses                = attrs[:responses] || []
         end
 
         # Documentation for a request parameter for an API action.

data/lib/useless/doc/core/resource.rb

@@ -24,7 +24,7 @@ module Useless
         def initialize(attrs = {})
           @path         = attrs[:path]
           @description  = attrs[:description]
-          @requests     = attrs[:requests]
+          @requests     = attrs[:requests] || []
         end
       end
     end

data/lib/useless/doc/core/response.rb

@@ -26,7 +26,7 @@ module Useless
         def initialize(attrs = {})
           @code         = attrs[:code]
           @description  = attrs[:description]
-          @headers      = attrs[:headers]
+          @headers      = attrs[:headers] || []
           @body         = attrs[:body]
         end
       end

data/lib/useless/doc/dsl.rb

@@ -84,6 +84,14 @@ module Useless
           @attributes[:description] = description
         end
 
+        def timestamp(timestamp)
+          if timestamp.is_a?(String)
+            timestamp = Time.parse(timestamp)
+          end
+
+          @attributes[:timestamp] = timestamp
+        end
+
         def api(name, &block)
           api = API.build name: name, &block
           @attributes[:apis] << api

data/lib/useless/doc/router.rb

@@ -11,6 +11,16 @@ module Useless
         @default ||= Doc::Router::Default.new
       end
 
+      def self.uri_for(raw_url)
+        url = raw_url.dup
+
+        unless url =~ /^https?:\/\//
+          url = 'http://' + url
+        end
+
+        URI(url)
+      end
+
       def doc_for_api(url)
       end
 
@@ -26,7 +36,7 @@ module Useless
 
         def doc_for_api(url)
           return nil unless supported_url?(url)
-          uri = URI(url)
+          uri = Router.uri_for(url)
           host = uri.host
           new_host = host.
             split('.').
@@ -36,7 +46,7 @@ module Useless
         end
 
         def api_for_doc(url)
-          uri = URI(url)
+          uri = Router.uri_for(url)
           host = uri.host
           parts = host.split('.')
           parts.slice!(-3) if parts[-3] == 'doc'

data/lib/useless/doc/serialization/dump.rb

@@ -30,6 +30,7 @@ module Useless
               'name' => domain.name,
               'url' => domain.url,
               'description' => domain.description,
+              'timestamp' => domain.timestamp ? domain.timestamp.iso8601 : nil,
               'apis' => domain.apis.map { |api| api(api) }
           end
         end
@@ -46,6 +47,7 @@ module Useless
               'name' => api.name,
               'url' => api.url,
               'description' => api.description,
+              'timestamp' => api.timestamp ? api.timestamp.iso8601 : nil,
               'resources' => api.resources.map { |resource| resource(resource) }
           end
         end

data/lib/useless/doc/serialization/load.rb

@@ -51,9 +51,16 @@ module Useless
             api json
           end
 
+          timestamp = begin
+            Time.parse(hash['timestamp'])
+          rescue TypeError, ArgumentError
+            nil
+          end
+
           Useless::Doc::Core::Domain.new \
             name:         hash['name'], 
             url:          hash['url'],
+            timestamp:    timestamp,
             description:  hash['description'],
             apis:         apis
         end
@@ -73,9 +80,16 @@ module Useless
             resource json
           end
 
+          timestamp = begin
+            Time.parse(hash['timestamp'])
+          rescue TypeError, ArgumentError
+            nil
+          end
+
           Useless::Doc::Core::API.new \
             name:         hash['name'], 
             url:          hash['url'],
+            timestamp:    timestamp,
             description:  hash['description'],
             resources:    resources
         end

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

@@ -30,8 +30,8 @@
   </header>
 
   <section class="main description">
-    <article>
-      <p class="description api">{{description}}</p>
+    <article class="description api">
+      {{{description}}}
     </article>
   </section>
 

data/lib/useless/doc/ui/godel/domain.mustache

@@ -13,14 +13,14 @@
       <section class="api header-section">
         <a class="name header-section-title" href="{{doc_url}}">{{name}}</a>
 
-        <p class="description">{{description}}</p>
+        {{{description}}}
       </section>
     {{/apis}}
   </header>
 
   <section class="main description">
-    <article>
-      <p class="description domain">{{description}}</p>
+    <article class="description domain">
+      {{{description}}}
     </article>
   </section>
 </body>

data/lib/useless/doc/ui/godel/stylesheet.css

@@ -10,6 +10,7 @@ h1, h2, h3, h4 {
   font-family: 'Open Sans Condensed', sans-serif;
   margin-top: 0;
   margin-bottom: 0.25em;
+  color: #333;
 }
 
 h2 {
@@ -35,11 +36,19 @@ h4 span.content-type {
   font-size: 0.75em;
 }
 
-p.description {
-  color: #888;
+article.description {
+  color: #555;
   margin-top: 0;
 }
 
+article.description code {
+  font-family: 'Courier New', 'Courier', monospace;
+}
+
+article.description h2 {
+  margin-bottom: 0.25em;
+}
+
 p.description.request {
   margin-bottom: 0.5em;
 }
@@ -71,7 +80,7 @@ header section.header-section.api {
 }
 
 header section.header-section p {
-  margin-bottom: 0.75em;
+  margin: 0.25em 0 0.75em;
 }
 
 header section.header-section a.header-section-title {
@@ -85,7 +94,7 @@ header section.header-section td.description {
 
 section.main {
   position: relative;
-  margin-left: 313px;
+  margin-left: 303px;
   min-width: 520px;
 }
 

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

@@ -1,6 +1,7 @@
 require 'mustache'
 require 'forwardable'
 require 'rack/utils'
+require 'redcarpet'
 
 require 'useless/doc/core/domain'
 require 'useless/doc/core/api'
@@ -16,6 +17,14 @@ module Useless
           File.dirname(__FILE__) + '/godel'
         end
 
+        def self.markdown
+          @markdown ||= Redcarpet::Markdown.new(Redcarpet::Render::HTML,
+            :no_intra_emphasis => true, :tables => true,
+            :fenced_code_blocks => true,:autolink => true,
+            :space_after_headers => true, :lax_spacing => true,
+            :superscript => true)
+        end
+
         def initialize(router)
           @router = router
         end
@@ -39,7 +48,7 @@ module Useless
         class Domain < Mustache
           extend Forwardable
 
-          def_delegators :@domain, :name, :description
+          def_delegators :@domain, :name
 
           self.template_file = Godel.asset_path + '/domain.mustache'
 
@@ -48,6 +57,10 @@ module Useless
             @router = router
           end
 
+          def description
+            Godel.markdown.render(@domain.description)
+          end
+
           def apis
             @domain.apis.map{ |api| Godel::API.new(api, @router) }
           end
@@ -56,7 +69,7 @@ module Useless
         class API < Mustache
           extend Forwardable
 
-          def_delegators :@api, :name, :url, :description
+          def_delegators :@api, :name, :url
 
           self.template_file = Godel.asset_path + '/api.mustache'
 
@@ -69,6 +82,10 @@ module Useless
             @router.doc_for_api(@api.url)
           end
 
+          def description
+            Godel.markdown.render(@api.description)
+          end
+
           def resources
             @api.resources.map{ |resource| Godel::Resource.new(resource, @router) }
           end

data/lib/useless/doc/version.rb

@@ -1,5 +1,5 @@
 module Useless
   module Doc
-    VERSION = '0.3.1'
+    VERSION = '0.4.0'
   end
 end

data/spec/documents/api.json

@@ -1,6 +1,7 @@
 {
   "name": "Twonk API",
   "url": "twonk.useless.io",
+  "timestamp": "2013-03-06T23:13:00-05:00",
   "description": "Twonk information. Duh.",
   "resources": [
     {

data/spec/documents/domain.json

@@ -1,6 +1,7 @@
 {
   "name": "Useless",
   "url": "http://useless.io",
+  "timestamp": "2013-03-06T23:13:00-05:00",
   "description": "A collection of useless APIs.",
   "apis": [
     {

data/spec/useless/doc/dsl_spec.rb

@@ -11,6 +11,7 @@ describe Useless::Doc::DSL::Domain do
       domain = Useless::Doc.domain 'useless.io' do
         url 'http://useless.io'
         description 'A collection of useless APIs.'
+        timestamp '2013-03-06 11:13 PM'
 
         api 'Twonk' do
           url 'twonk.useless.io'
@@ -21,6 +22,7 @@ describe Useless::Doc::DSL::Domain do
       domain.name.should == 'useless.io'
       domain.url.should == 'http://useless.io'
       domain.description.should == 'A collection of useless APIs.'
+      domain.timestamp.should == Time.parse('2013-03-06 11:13 PM')
 
       domain.apis.first.name.should == 'Twonk'
       domain.apis.first.url.should == 'twonk.useless.io'

data/spec/useless/doc/router_spec.rb

@@ -18,6 +18,11 @@ describe Useless::Doc::Router::Default do
     it 'should return nil if the specified URL is not part of the domain' do
       @router.doc_for_api('http://nonexistant.domain.com/some/path').should be_nil
     end
+
+    it 'should handle URLs that are missing a scheme' do
+      @router.doc_for_api('api.domain.com/some/path').
+        should == 'http://api.doc.domain.com/some/path'
+    end
   end
 
   describe '.api_for_doc' do
@@ -34,5 +39,10 @@ describe Useless::Doc::Router::Default do
     it 'should return nil if the resulting URL is not part of the domain' do
       @router.api_for_doc('http://nonexistant.doc.domain.com/some/path').should be_nil
     end
+
+    it 'should handle URLs that are missing a scheme' do
+      @router.api_for_doc('api.doc.domain.com/some/path').
+        should == 'http://api.domain.com/some/path'
+    end
   end
 end

data/spec/useless/doc/serialization/dump_spec.rb

@@ -33,6 +33,7 @@ describe Useless::Doc::Serialization::Dump do
       domain = Useless::Doc::Core::Domain.new \
         name: 'Useless',
         url: 'http://useless.io',
+        timestamp: Time.parse('2013-03-06 11:13 PM'),
         description: 'A collection of useless APIs.',
         apis: [api]
 
@@ -40,6 +41,7 @@ describe Useless::Doc::Serialization::Dump do
       hash = Useless::Doc::Serialization::Load.json_to_hash(json)
       hash['name'].should == 'Useless'
       hash['url'].should == 'http://useless.io'
+      hash['timestamp'].should == Time.parse('2013-03-06 11:13 PM').iso8601
       hash['description'].should == 'A collection of useless APIs.'
 
       api_hash = Useless::Doc::Serialization::Load.json_to_hash(hash['apis'][0])
@@ -59,6 +61,7 @@ describe Useless::Doc::Serialization::Dump do
       api = Useless::Doc::Core::API.new \
         name: 'Twiddles API',
         url: 'twiddles.useless.io',
+        timestamp: Time.parse('2013-03-06 11:13 PM'),
         description: 'Pretty much, like, everything you\'re looking for',
         resources: [resource]
 
@@ -66,6 +69,7 @@ describe Useless::Doc::Serialization::Dump do
       hash = Useless::Doc::Serialization::Load.json_to_hash(json)
       hash['name'].should == 'Twiddles API'
       hash['url'].should == 'twiddles.useless.io'
+      hash['timestamp'].should == Time.parse('2013-03-06 11:13 PM').iso8601
       hash['description'].should == 'Pretty much, like, everything you\'re looking for'
 
       resource_hash = Useless::Doc::Serialization::Load.json_to_hash(hash['resources'][0])

data/spec/useless/doc/serialization/load_spec.rb

@@ -45,6 +45,7 @@ describe Useless::Doc::Serialization::Load do
       domain = Useless::Doc::Serialization::Load.domain document.read
       domain.name.should == 'Useless'
       domain.url.should == 'http://useless.io'
+      domain.timestamp.should == Time.parse('2013-03-06T23:13:00-05:00')
       domain.description.should == 'A collection of useless APIs.'
       domain.apis.first.name.should == 'The Jah API'
       domain.apis.first.url.should == 'http://jah.useless.io'
@@ -58,6 +59,7 @@ describe Useless::Doc::Serialization::Load do
       api = Useless::Doc::Serialization::Load.api document.read
       api.name.should == 'Twonk API'
       api.url.should == 'twonk.useless.io'
+      api.timestamp.should == Time.parse('2013-03-06T23:13:00-05:00')
       api.description.should == 'Twonk information. Duh.'
       api.resources.first.path.should == '/twonks/:id'
       api.resources.first.description.should == 'The most critical aspect.'

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

@@ -2,6 +2,8 @@ require File.dirname(__FILE__) + '/../../../spec_helper'
 
 require 'nokogiri'
 require 'useless/doc'
+require 'useless/doc/core/domain'
+require 'useless/doc/core/api'
 require 'useless/doc/router'
 require 'useless/doc/ui/godel'
 
@@ -9,10 +11,10 @@ describe Useless::Doc::UI::Godel do
   describe '.html' do
     context 'for a Core::Domain instance' do
       before(:all) do
-        router = Useless::Doc::Router.default
+        @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)
+        result = Useless::Doc::UI::Godel.new(@router).html(domain)
         @doc = Nokogiri::HTML(result)
       end
 
@@ -23,11 +25,25 @@ describe Useless::Doc::UI::Godel do
       end
 
       it 'should render the domain description in an article p' do
-        description = @doc.css('article p.description.domain')
+        description = @doc.css('article.description.domain p')
         description.length.should == 1
         description.first.content.should == 'A collection of useless APIs.'
       end
 
+      it 'should not escape the description text' do
+        domain = Useless::Doc::Core::Domain.new description: '<span>The description</span>'
+        result = Useless::Doc::UI::Godel.new(@router).html(domain)
+        description = Nokogiri::HTML(result).css('article.description.domain p')
+        description.first.inner_html.should == '<span>The description</span>'
+      end
+
+      it 'should interpret Markdown for the description' do
+        domain = Useless::Doc::Core::Domain.new description: '*The description*'
+        result = Useless::Doc::UI::Godel.new(@router).html(domain)
+        description = Nokogiri::HTML(result).css('article.description.domain p')
+        description.first.inner_html.should == '<em>The description</em>'
+      end
+
       it 'should render API names as a\'s, with correct doc URLs' do
         as = @doc.css('a.name')
         as.length.should == 2
@@ -58,11 +74,25 @@ describe Useless::Doc::UI::Godel do
       end
 
       it 'should render the API description in an article p' do
-        description = @doc.css('article p.description.api')
+        description = @doc.css('article.description.api p')
         description.length.should == 1
         description.first.content.should == 'Twonk information. Duh.'
       end
 
+      it 'should not escape the description text' do
+        domain = Useless::Doc::Core::API.new description: '<span>The description</span>'
+        result = Useless::Doc::UI::Godel.new(@router).html(domain)
+        description = Nokogiri::HTML(result).css('article.description.api p')
+        description.first.inner_html.should == '<span>The description</span>'
+      end
+
+      it 'should interpret Markdown for the description' do
+        domain = Useless::Doc::Core::API.new description: '*The description*'
+        result = Useless::Doc::UI::Godel.new(@router).html(domain)
+        description = Nokogiri::HTML(result).css('article.description.api p')
+        description.first.inner_html.should == '<em>The description</em>'
+      end
+
       it 'should render resouce paths as a\'s' do
         as = @doc.css('a.path')
         as.length.should == 2

data/useless-doc.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |gem|
   gem.add_dependency 'low',                   '~> 0.0.17'
   gem.add_dependency 'sinatra',               '~> 1.3.4'
   gem.add_dependency 'mustache',              '~> 0.99.4'
+  gem.add_dependency 'redcarpet',             '~> 2.2.2'
 
   gem.add_development_dependency 'rspec',     '~> 2.12.0'
   gem.add_development_dependency 'rack-test', '~> 0.6.2'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: useless-doc
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-23 00:00:00.000000000 Z
+date: 2013-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -107,6 +107,22 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 0.99.4
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.2.2
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement