useless-doc 0.2.3 → 0.3.0

data/lib/useless/doc/client.rb

@@ -0,0 +1,62 @@
+require 'time'
+require 'typhoeus'
+require 'uri'
+
+require 'useless/doc/serialization/load'
+
+module Useless
+  module Doc
+    module Client
+      def self.standard
+        @standard ||= Standard.new
+      end
+
+      def self.stub
+        @stub ||= Stub.new
+      end
+
+      def get(url)
+        nil
+      end
+
+      class Standard
+        include Client
+
+        NotModified = 304
+
+        def initialize
+          @cache = {}
+        end
+
+        def get(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] = { response_body: response.response_body, timestamp: Time.now }
+          end
+
+          Useless::Doc::Serialization::Load.load(@cache[url][:response_body])
+        end
+      end
+
+      class Stub
+        include Client
+
+        def get(url)
+          uri = URI(url)
+          path = File.dirname(__FILE__) + "/../../../spec/documents#{uri.path}.json"
+
+          if File.exists?(path)
+            Useless::Doc::Serialization::Load.load(File.read(path))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -4,6 +4,9 @@ module Useless
 
       # Documentation for an entire API.
       #
+      # @!attribute [r] name
+      #   @return [String] nameof the API.
+      #
       # @!attribute [r] url
       #   @return [String] a the URL of the API.
       #
@@ -18,15 +21,16 @@ module Useless
       #
       class API
 
-        attr_accessor :url, :description, :timestamp, :resources
+        attr_accessor :name, :url, :description, :timestamp, :resources
 
         # @param [Hash] attrs corresponds to the class's instance attributes.
         #
         def initialize(attrs = {})
+          @name = attrs[:name]
           @url = attrs[:url]
           @description = attrs[:description]
           @timestamp = attrs[:timestamp]
-          @resources = attrs[:resources]
+          @resources = attrs[:resources] || []
         end
       end
     end

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

@@ -0,0 +1,34 @@
+module Useless
+  module Doc
+    module Core
+
+      # Documentation for a domain - a group of APIs.
+      #
+      # @!attribute [r] name
+      #   @return [String] a name of the domain.
+      #
+      # @!attribute [r] url
+      #   @return [String] a the URL of the domain.
+      #
+      # @!attribute [r] description
+      #   @return [String] a description of the domain.
+      #
+      # @!attribute [r] apis
+      #   @return [Array<API>] the APIs included in this domain.
+      #
+      class Domain
+
+        attr_accessor :name, :url, :description, :apis
+
+        # @param [Hash] attrs corresponds to the class's instance attributes.
+        #
+        def initialize(attrs = {})
+          @name = attrs[:name]
+          @url = attrs[:url]
+          @description = attrs[:description]
+          @apis = attrs[:apis]
+        end
+      end
+    end
+  end
+end

data/lib/useless/doc/dsl.rb

@@ -1,5 +1,6 @@
 require 'useless/doc/core/api'
 require 'useless/doc/core/body'
+require 'useless/doc/core/domain'
 require 'useless/doc/core/header'
 require 'useless/doc/core/request'
 require 'useless/doc/core/resource'
@@ -64,6 +65,31 @@ module Useless
         end
       end
 
+      class Domain
+        include DSL::Member
+
+        def default_attributes
+          { apis: [] }
+        end
+
+        def name
+          @attributes[:name] = name
+        end
+
+        def url(url)
+          @attributes[:url] = url
+        end
+
+        def description(description)
+          @attributes[:description] = description
+        end
+
+        def api(name, &block)
+          api = API.build name: name, &block
+          @attributes[:apis] << api
+        end
+      end
+
       class API
         include DSL::Member
 
@@ -84,6 +110,10 @@ module Useless
           super
         end
 
+        def name
+          @attributes[:name] = name
+        end
+
         def url(url)
           @attributes[:url] = url
         end

data/lib/useless/doc/rack/{stylesheet.rb → css.rb}

@@ -1,22 +1,22 @@
 module Useless
   module Doc
-    module Rack
+    class Rack
 
-      # +Doc::Rack::Stylesheet+ serves the stylesheet for the current +Doc::UI+
+      # +Doc::Rack::CSS+ serves the stylesheet for the current +Doc::UI+
       # iff the request path is '/doc.css'. Otherwise, it passes the request
-      # through.
+      # down the stack.
       # 
-      class Stylesheet
+      class CSS
         def initialize(app)
           @app = app
         end
 
         def call(env)
-          unless env['useless.doc.ui']
-            raise 'No UI specified.'
-          end
-
           if env["PATH_INFO"].to_s == '/doc.css'
+            if env['useless.doc.logger']
+              env['useless.doc.logger'].info "serving CSS for #{env['useless.doc.ui'].class.name}"
+            end
+
             [200, {'Content-Type' => 'text/css'}, [env['useless.doc.ui'].css]]
           else
             @app.call(env)

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

@@ -0,0 +1,26 @@
+module Useless
+  module Doc
+    class Rack
+
+      # +Doc::Rack::HTML+ is the base application for +Useless::Doc::Rack+.
+      # It expects a +Doc::UI+ instance to be set as 'useless.doc.ui', and a
+      # +Doc::Core+ entity to be set as 'useless.doc.subject', and then simply
+      # passes the latter to the former's +#html+ method.
+      #
+      module HTML
+        def self.call(env)
+          if html = env['useless.doc.ui'].html(env['useless.doc.subject'])
+            if env['useless.doc.logger']
+              env['useless.doc.logger'].info "rendered subject HTML for #{env['useless.doc.url']}"
+              env['useless.doc.logger'].debug "rendered HTML: #{html}"
+            end
+
+            [200, {'Content-Type' => 'text/html'}, [html]]
+          else
+            [404, {'Content-Type' => 'text/plain'}, ['Could not render documentation.']]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+require 'useless/doc/client'
+
+module Useless
+  module Doc
+    class Rack
+
+      # +Doc::Rack::Subject+ retrieves a +Doc::Core+ entity based upon
+      # 'useless.doc.url', from a environment-appropriate +Doc::Client+,
+      # and sets it to 'useless.doc.subject'.
+      #
+      class Subject
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          client = case ENV['RACK_ENV']
+            when 'production'; Useless::Doc::Client.standard
+            else               Useless::Doc::Client.stub
+          end
+
+          if env['useless.doc.logger']
+            env['useless.doc.logger'].debug "selected Client: #{client.inspect}"
+          end
+
+          if env['useless.doc.subject'] = client.get(env['useless.doc.url'])
+            if env['useless.doc.logger']
+              env['useless.doc.logger'].info "retrieved subject for #{env['useless.doc.url']}"
+              env['useless.doc.logger'].debug "retrieved subject: #{env['useless.doc.subject'].inspect}"
+            end
+
+            @app.call(env)
+          else
+            [404, {'Content-Type' => 'text/plain'}, ['Could not retrieve documentation.']]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,17 +3,15 @@ require 'useless/doc/ui/godel'
 
 module Useless
   module Doc
-    module Rack
+    class Rack
 
       # +Doc::Rack::UI+ chooses which UI should be used to render the
-      # documentation. It can theoretically be chosen via the 'ui' parameter,
-      # but for now it will alway choose +Godel+
+      # documentation and sets it to 'useless.doc.ui'.
+      #
+      # It could theoretically be chosen via the 'ui' parameter,
+      # but until there are other UIs, it will alway choose +UI::Godel+.
       #
       class UI
-        def self.default
-          Useless::Doc::UI::Godel
-        end
-
         def initialize(app)
           @app = app
         end
@@ -21,12 +19,15 @@ module Useless
         def call(env)
           request = ::Rack::Request.new(env)
 
-          ui = case request.params['ui']
-          when 'godel' then Useless::Doc::UI::Godel
-          else              Rack::UI.default
+          env['useless.doc.ui'] = case request.params['ui']
+            when 'godel'; Useless::Doc::UI::Godel.new(env['useless.doc.router'])
+            else          Useless::Doc::UI::Godel.new(env['useless.doc.router'])
+          end
+
+          if env['useless.doc.logger']
+            env['useless.doc.logger'].debug "selected UI: #{env['useless.doc.ui'].class.name}"
           end
 
-          env['useless.doc.ui'] = ui
           @app.call(env)
         end
       end

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

@@ -0,0 +1,33 @@
+require 'rack/request'
+
+module Useless
+  module Doc
+    class Rack
+
+      # +Doc::Rack::URL+ translates the request URL into the corresponding
+      # API URL using the specified 'useless.doc.router'.
+      #
+      class URL
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          request = ::Rack::Request.new(env)
+
+          if url = env['useless.doc.router'].api_for_doc(request.url)
+            env['useless.doc.url'] = url
+
+            if env['useless.doc.logger']
+              env['useless.doc.logger'].info "routing #{request.url} to #{env['useless.doc.url']}"
+            end
+
+            @app.call(env)
+          else
+            [404, {'Content-Type' => 'text/plain'}, ['Unknown documentation.']]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/useless/doc/rack.rb

@@ -0,0 +1,46 @@
+require 'rack/builder'
+require 'rack/commonlogger'
+require 'low/rack/rack_errors'
+require 'low/rack/log_level'
+require 'low/rack/request_logger'
+
+require 'useless/doc/router'
+require 'useless/doc/rack/ui'
+require 'useless/doc/rack/css'
+require 'useless/doc/rack/url'
+require 'useless/doc/rack/subject'
+require 'useless/doc/rack/html'
+
+module Useless
+  module Doc
+    class Rack
+      def initialize(router = nil)
+        @router = router || Useless::Doc::Router.default
+      end
+
+      def call(env)
+        env['useless.doc.router'] ||= @router
+        app.call(env)
+      end
+
+      private
+
+      def app
+        @app ||= begin
+          ::Rack::Builder.app do
+            use Low::Rack::RackErrors
+            use Low::Rack::LogLevel
+            use Low::Rack::RequestLogger, key: 'useless.doc.logger'
+            use ::Rack::CommonLogger
+
+            use Useless::Doc::Rack::UI
+            use Useless::Doc::Rack::CSS
+            use Useless::Doc::Rack::URL
+            use Useless::Doc::Rack::Subject
+            run Useless::Doc::Rack::HTML
+          end
+        end
+      end
+    end
+  end
+end

data/lib/useless/doc/router.rb

@@ -0,0 +1,62 @@
+require 'uri'
+
+module Useless
+  module Doc
+
+    # +Doc::Router+ determines the doc URL for an API and vice versa via
+    # the #doc_for_api and #api_for_doc methods, respectively.
+    #
+    module Router
+      def self.default
+        @default ||= Doc::Router::Default.new
+      end
+
+      def doc_for_api(url)
+      end
+
+      def api_for_doc(url)
+      end
+
+      class Default
+        include Doc::Router
+
+        def initialize(*supported_urls)
+          @supported_urls = supported_urls
+        end
+
+        def doc_for_api(url)
+          return nil unless supported_url?(url)
+          uri = URI(url)
+          host = uri.host
+          new_host = host.
+            split('.').
+            insert(-3, 'doc').
+            join('.')
+          "#{uri.scheme}://#{new_host}#{uri.path}"
+        end
+
+        def api_for_doc(url)
+          uri = URI(url)
+          host = uri.host
+          parts = host.split('.')
+          parts.slice!(-3) if parts[-3] == 'doc'
+          new_host = parts.join('.')
+          new_url = "#{uri.scheme}://#{new_host}#{uri.path}"
+          new_url if supported_url?(new_url)
+        end
+
+        private
+
+        def supported_url?(url)
+          if @supported_urls.nil? or @supported_urls.empty?
+            true
+          else
+            @supported_urls.any? do |supported_url|
+              url =~ Regexp.new(supported_url)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -18,6 +18,22 @@ module Useless
           hash.is_a?(String) ? hash : Oj.dump(hash)
         end
 
+        # Converts +Core::Domain+ instance to a JSON representation.
+        #
+        # @param [Core::Domain] domain the domain to be converted to JSON.
+        #
+        # @return [String] a JSON representation of the specified domain.
+        #
+        def self.domain(domain)
+          if domain
+            hash_to_json \
+              'name' => domain.name,
+              'url' => domain.url,
+              'description' => domain.description,
+              'apis' => domain.apis.map { |api| api(api) }
+          end
+        end
+
         # Converts +Core::API+ instance to a JSON representation.
         #
         # @param [Core::API] api the API to be converted to JSON.
@@ -27,6 +43,7 @@ module Useless
         def self.api(api)
           if api
             hash_to_json \
+              'name' => api.name,
               'url' => api.url,
               'description' => api.description,
               'resources' => api.resources.map { |resource| resource(resource) }

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

@@ -24,6 +24,40 @@ module Useless
           json.is_a?(Hash) ? json : Oj.load(json)
         end
 
+        def self.load(json)
+          hash = json_to_hash json
+
+          if hash['apis']
+            self.domain(hash)
+          elsif hash['url']
+            self.api(hash)
+          elsif hash['path']
+            self.resource(hash)
+          end
+        end
+
+        # Converts a JSON represntation to an instance of +Core::Domain+
+        #
+        # @param [String, Hash] json the JSON representation to be converted to
+        #   a domain.
+        #
+        # @return [Core::Domain] the domain corresponding to the specified
+        #   JSON.
+        #
+        def self.domain(json)
+          hash = json_to_hash json
+
+          apis = (hash['apis'] || []).map do |json|
+            api json
+          end
+
+          Useless::Doc::Core::Domain.new \
+            name:         hash['name'], 
+            url:          hash['url'],
+            description:  hash['description'],
+            apis:         apis
+        end
+
         # Converts a JSON represntation to an instance of +Core::API+
         #
         # @param [String, Hash] json the JSON representation to be converted to
@@ -40,6 +74,7 @@ module Useless
           end
 
           Useless::Doc::Core::API.new \
+            name:         hash['name'], 
             url:          hash['url'],
             description:  hash['description'],
             resources:    resources

data/lib/useless/doc/sinatra.rb

@@ -15,7 +15,8 @@ module Useless
     #   class ResourceApp < Sinatra::Base
     #     register Useless::Doc::Sinatra
     #
-    #     doc 'resources.useless.io' do
+    #     doc 'Resouces API' do
+    #       url 'resources.useless.io'
     #       description 'A place with resources'
     #     end
     #
@@ -42,8 +43,8 @@ module Useless
         @doc = doc
       end
 
-      def doc(url = nil, &block)
-        @dsl ||= Useless::Doc::DSL::API.new(url: url)
+      def doc(name = nil, &block)
+        @dsl ||= Useless::Doc::DSL::API.new(name: name)
         @dsl.instance_eval(&block) if block_given?
         @dsl
       end

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

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

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

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>doc.useless.io</title>
+  <link href="/doc.css" media="screen" rel="stylesheet" type="text/css" />
+</head>
+<body>
+
+  <header class="domain">
+    <h1>{{name}}</h1>
+
+    {{#apis}}
+      <section class="api header-section">
+        <a class="name header-section-title" href="{{doc_url}}">{{name}}</a>
+
+        <p class="description">{{description}}</p>
+      </section>
+    {{/apis}}
+  </header>
+
+  <section class="main description">
+    <article>
+      <p class="description domain">{{description}}</p>
+    </article>
+  </section>
+</body>