raddocs 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e05f829e0cb6d404ed14e8abb6942d9f4714527f
-  data.tar.gz: 93f7a97e38c9dc952860438be5eef3c2767cc31b
+  metadata.gz: 51c3f683fc4b32ffe21f3b00883e54ede5f9874d
+  data.tar.gz: 04fb0bab660edaca38e10723ac9a7ab16ff2b795
 SHA512:
-  metadata.gz: 92806b37addee4f7ca3aa9d5caf01c2ae6161e3f21a7cdcae9f8162b0c98e4cc651bba1d345b628107f7ae1e540c2fd7e131238d3ad993fbe121808d827ad965
-  data.tar.gz: 1758b0a4e9b412d3fe10b8057398446a48634dba436a14a02fed4a280a351514c183f251002665efbd3ca03bd8bb95cd414a442f5968d920738d307cb9ae6dca
+  metadata.gz: 7236230c824fe40288d3ae3bf972249c056a111789f03db775adecc452b9bdc9d44a92a31fb9adc21c12769cdecdc018d0a1949d6cf9526b0179ad70dbecb18d
+  data.tar.gz: cd3d939196c54291544192b8e968499f9297947c5526d26ce5dd817c36169c0cd9d6c808d160d3bb6bb543979cff836b68271f24c7edbcd09abd49a6a7f0423a

data/lib/public/application.css

@@ -1,7 +1,9 @@
 body {
 	margin: 25px 0;
 }
-
+.container{
+  margin-top: 25px;
+}
 .response .body .content, .request .body .content {
     background-color: #f5f5f5;
     margin: 0;

data/lib/raddocs.rb

@@ -2,16 +2,27 @@ Encoding.default_external = Encoding::UTF_8
 
 require 'sinatra/base'
 require 'json'
+
 require 'raddocs/configuration'
 require 'raddocs/app'
 require 'raddocs/middleware'
-require 'raddocs/parameters'
+
+require 'raddocs/models'
 
 module Raddocs
+  # @return [Raddocs::Configuration] the current configuration
   def self.configuration
     @configuration ||= Configuration.new
   end
 
+  # Configure Raddocs
+  #
+  # @example
+  #   Raddocs.configure do |config|
+  #     config.url_prefix = "/documentation"
+  #   end
+  #
+  # @yieldparam configuration [Raddocs::Configuration]
   def self.configure
     yield configuration if block_given?
   end

data/lib/raddocs/app.rb

@@ -1,13 +1,16 @@
 module Raddocs
+  # Sinatra app that serves all documentation
   class App < Sinatra::Base
     set :haml, :format => :html5
     set :root, File.join(File.dirname(__FILE__), "..")
 
+    # Main index, displays all examples grouped by resource
     get "/" do
-      index = JSON.parse(File.read("#{docs_dir}/index.json"))
+      index = Index.new(File.join(docs_dir, "index.json"))
       haml :index, :locals => { :index => index }
     end
 
+    # Allows for overriding styles
     get "/custom-css/*" do
       file = "#{docs_dir}/styles/#{params[:splat][0]}"
 
@@ -19,6 +22,11 @@ module Raddocs
       File.read(file)
     end
 
+    # Catch all for example pages.
+    # Loads files from the docs dir and appends '.json'.
+    #
+    # @example
+    #   "/orders/create_an_order" => "docs/api/orders/create_an_order.json"
     get "/*" do
       file = "#{docs_dir}/#{params[:splat][0]}.json"
 
@@ -26,13 +34,13 @@ module Raddocs
         raise Sinatra::NotFound
       end
 
-      file_content = File.read(file)
+      index = Index.new(File.join(docs_dir, "index.json"))
+      example = Example.new(file)
 
-      example = JSON.parse(file_content)
-      example["parameters"] = Parameters.new(example["parameters"]).parse
-      haml :example, :locals => { :example => example }
+      haml :example, :locals => { index: index, example: example }
     end
 
+    # Page not found
     not_found do
       "Example does not exist"
     end
@@ -56,6 +64,9 @@ module Raddocs
         Raddocs.configuration.api_name
       end
 
+      # Loads all necessary css files
+      #
+      # @see Raddocs::Configuration for loading external files
       def css_files
         files = ["#{url_location}/codemirror.css", "#{url_location}/application.css"]
 
@@ -72,10 +83,10 @@ module Raddocs
 
         files
       end
-    end
 
-    def docs_dir
-      Raddocs.configuration.docs_dir
+      def docs_dir
+        Raddocs.configuration.docs_dir
+      end
     end
   end
 end

data/lib/raddocs/configuration.rb

@@ -1,5 +1,17 @@
 module Raddocs
+  # Configure Raddocs
+  # @see Raddocs.configure Raddocs.configure
+  # @example
+  #   Raddocs.configure do |config|
+  #     # config is this class
+  #     config.api_name = "My API"
+  #   end
   class Configuration
+    # Configures a new setting, creates two methods
+    #
+    # @param name [Symbol] name of the setting
+    # @param opts [Hash]
+    # @option opts [Object] default default value of setting
     def self.add_setting(name, opts = {})
       define_method("#{name}=") { |value| settings[name] = value }
       define_method("#{name}") do
@@ -13,13 +25,32 @@ module Raddocs
       end
     end
 
+    # @!attribute docs_dir
+    # @return [String] defaults to 'doc/api'
     add_setting :docs_dir, :default => "doc/api"
+
+    # @!attribute docs_mime_type
+    # @return [Regexp] defaults to Regexp.new("text/docs\+plain")
     add_setting :docs_mime_type, :default => /text\/docs\+plain/
+
+    # @!attribute api_name
+    # @return [String] defaults to "Api Documentation"
     add_setting :api_name, :default => "Api Documentation"
+
+    # @!attribute include_bootstrap
+    # @return [Boolean] defaults to true
     add_setting :include_bootstrap, :default => true
+
+    # @!attribute external_css
+    # @return [Array] array of Strings, defaults to []
     add_setting :external_css, :default => []
+
+    # @!attribute url_prefix
+    # @return [String] defaults to nil
     add_setting :url_prefix, :default => nil
 
+    private
+
     def settings
       @settings ||= {}
     end

data/lib/raddocs/middleware.rb

@@ -1,4 +1,15 @@
 module Raddocs
+  # Rack middleware
+  #
+  # This lets you cURL for documentation.
+  #
+  #   curl -H "Accept: text/docs+plain" http://localhost/orders
+  #
+  # This will return all of the docs for a given resource, "orders." It is returned
+  # as a giant flat file containing all of the documentation. "combined_text" output
+  # must be selected in `rspec_api_documentation`.
+  #
+  # The route matches the folder structure of the docs.
   class Middleware
     def initialize(app)
       @app = app

data/lib/raddocs/models.rb

@@ -0,0 +1,295 @@
+module Raddocs
+  # Index page model
+  class Index
+    def initialize(file)
+      @attrs = JSON.parse(File.read(file))
+    end
+
+    # @return [Array] array of {Raddocs::Resource Resources}
+    def resources
+      @attrs.fetch("resources", {}).map do |resource|
+        Resource.new(resource["name"], resource["examples"])
+      end
+    end
+  end
+
+  # Group of examples related to a specific resource, eg "Orders"
+  class Resource < Struct.new(:name, :examples)
+    # @return [Array] array of {Raddocs::IndexExample IndexExamples}
+    def examples
+      @examples ||= super.map do |example|
+        IndexExample.new(example)
+      end
+    end
+  end
+
+  # Example model for the index page
+  #
+  # Has an extra link attribute that is required only on this page.
+  class IndexExample
+    attr_reader :description, :link
+
+    def initialize(attributes)
+      @description = attributes.fetch("description")
+      @link = attributes.fetch("link")
+    end
+
+    # Link to example page is the same name as the file minus ".json"
+    def href
+      link.gsub(".json", "")
+    end
+  end
+
+  # Example page model
+  class Example
+    attr_reader :resource, :description, :explanation, :parameters, :response_fields,
+      :requests
+
+    def initialize(file)
+      @attrs = JSON.parse(File.read(file))
+
+      @resource = @attrs.fetch("resource")
+      @description = @attrs.fetch("description")
+      @explanation = @attrs.fetch("explanation", nil)
+      @parameters = Parameters.new(@attrs.fetch("parameters"))
+      @response_fields = ResponseFields.new(@attrs.fetch("response_fields"))
+      @requests = @attrs.fetch("requests").map { |request| Request.new(request) }
+    end
+
+    # @return [Boolean] true if explanation is present
+    def explanation?
+      !explanation.nil?
+    end
+  end
+
+  # An example's parameters, requires a class because the table can display unknown columns
+  class Parameters
+    attr_reader :extra_keys, :params
+
+    SPECIAL_KEYS = ["name", "description", "required", "scope"]
+
+    # Collection object for parameters to pull out unknown keys so they can be
+    # displayed on the example page.
+    #
+    # @example
+    #   params = Parameters.new([
+    #     {"name" => "page", "description" => "Page number", "Type" => "Integer"}
+    #   ])
+    #   params.extra_keys
+    #   # => ["Type"]
+    #
+    # @param params [Array] array of {Raddocs::Parameter Parameters}
+    #
+    def initialize(params)
+      @params = params.map { |param| Parameter.new(param) }
+      @extra_keys = params.flat_map(&:keys).uniq - SPECIAL_KEYS
+    end
+
+    # @return [Boolean] true if params contains elements
+    def present?
+      @params.count > 0
+    end
+  end
+
+  # Parameter of a request
+  #
+  # Can have an unknown columns
+  #
+  # @example
+  #   Parameter.new({
+  #     "name" => "page",
+  #     "description" => "Page number",
+  #     "Type" => "Integer"
+  #   })
+  #
+  class Parameter
+    attr_reader :name, :description, :required, :scope
+
+    # @param attributes [Hash]
+    # @option attributes [String] "name" Required
+    # @option attributes [String] "description" Required
+    # @option attributes [boolean] "required" defaults to false
+    # @option attributes [String] "scope" Scope of the parameter, eg 'order[]', defaults to nil
+    def initialize(attributes)
+      @attrs = attributes
+
+      @name = attributes.fetch("name")
+      @description = attributes.fetch("description")
+      @required = attributes.fetch("required", false)
+      @scope = attributes.fetch("scope", nil)
+    end
+
+    # @return [Boolean] true if required is true
+    def required?
+      !!@required
+    end
+
+    # @return [Boolean] true if scope is present
+    def scope?
+      !!@scope
+    end
+
+    def scope
+      Array(@scope).each_with_index.map do |scope, index|
+        if index == 0
+          scope
+        else
+          "[#{scope}]"
+        end
+      end.join
+    end
+
+    # Allows unknown keys to be accessed
+    # @param key [String]
+    # @return [Object]
+    def [](key)
+      @attrs[key]
+    end
+  end
+
+  # An example's response fields, requires a class because the table can display
+  # unknown columns
+  class ResponseFields
+    attr_reader :extra_keys, :fields
+
+    SPECIAL_KEYS = ["name", "description", "scope"]
+
+    def initialize(response_fields)
+      return unless response_fields # Might not be present
+      @fields = response_fields.map { |field| ResponseField.new(field) }
+      @extra_keys = response_fields.flat_map(&:keys).uniq - SPECIAL_KEYS
+    end
+
+    # @return [Boolean] true if fields contains elements
+    def present?
+      @fields.count > 0
+    end
+  end
+
+  # Fields of a response
+  #
+  # Can have an unknown columns
+  #
+  # @example
+  #   Parameter.new({
+  #     "name" => "page",
+  #     "description" => "Page number",
+  #     "Type" => "Integer"
+  #   })
+  #
+  class ResponseField
+    attr_reader :name, :description, :scope
+
+    def initialize(attributes)
+      @attrs = attributes
+
+      @name = attributes.fetch("name")
+      @description = attributes.fetch("description")
+      @scope = attributes.fetch("scope", nil)
+    end
+
+    # @return [Boolean] true if scope is present
+    def scope?
+      !!@scope
+    end
+
+    # Allows unknown keys to be accessed
+    # @param key [String]
+    # @return [Object]
+    def [](key)
+      @attrs[key]
+    end
+  end
+
+  # Documented response
+  #
+  # @param attributes [Hash]
+  class Request
+    attr_reader :request_method, :request_path, :request_body,
+      :curl, :response_status, :response_body
+
+    # @param attributes [Hash]
+    # @option attributes [Hash] "request_headers"
+    #   Hash of request headers, not in rack format
+    # @option attributes [String] "request_method"
+    # @option attributes [String] "request_path"
+    # @option attributes [Hash] "request_query_parameters"
+    #   Query parameters pulled from the request if a GET request
+    # @option attributes [String] "request_body"
+    # @option attributes [String] "curl" Formatted
+    #   cURL request
+    # @option attributes [String] "response_status"
+    # @option attributes [Hash] "response_headers"
+    #   Hash of response headers, not in rack format
+    # @option attributes [String] "response_body"
+    def initialize(attributes)
+      @attrs = attributes
+
+      @request_headers = attributes.fetch("request_headers")
+      @request_method = attributes.fetch("request_method")
+      @request_path = attributes.fetch("request_path")
+      @request_query_parameters = attributes.fetch("request_query_parameters", nil)
+      @request_body = attributes.fetch("request_body", nil)
+      @curl = attributes.fetch("curl", nil)
+      @response_status = attributes.fetch("response_status")
+      @response_headers = attributes.fetch("response_headers", {})
+      @response_body = attributes.fetch("response_body", nil)
+    end
+
+    # There are unwanted indents if this was a simple each and output in haml
+    def request_headers
+      @request_headers.map do |header, value|
+        "#{header}: #{value}"
+      end.join("\n")
+    end
+
+    # @return [String] joined query parameters, eg: "key=value\nkey=value"
+    def request_query_parameters
+      @request_query_parameters.map { |k,v| "#{k}=#{v}" }.join("\n")
+    end
+
+    # @return [Boolean] true if request query parameters are present
+    def request_query_parameters?
+      !@request_query_parameters.empty?
+    end
+
+    # @return [Boolean] true if request body is present
+    def request_body?
+      !@request_body.nil?
+    end
+
+    # Request headers must be set
+    # @return [String] Content type of the request
+    def request_content_type
+      @request_headers["Content-Type"]
+    end
+
+    # @return [Boolean] true if cURL command is present
+    def curl?
+      !@curl.nil?
+    end
+
+    # @return [Boolean] true if the response is present
+    def response?
+      !@response_status.nil?
+    end
+
+    # There are unwanted indents if this was a simple each and output in haml
+    def response_headers
+      @response_headers.map do |header, value|
+        "#{header}: #{value}"
+      end.join("\n")
+    end
+
+    # @return [Boolean] true if response body is present
+    def response_body?
+      !@response_body.nil?
+    end
+
+    # Response headers must be set
+    # @return [String] Content type of the response
+    def response_content_type
+      @response_headers["Content-Type"]
+    end
+  end
+end

data/lib/views/example.haml

@@ -27,99 +27,111 @@
 .nav-bar
   = link_to "« Back to Index", "/"
 
-%h1== #{example["resource"]} API
+%h1== #{example.resource} API
 .article
-  %h2= example["description"]
+  %h2= example.description
 
-  - if example["explanation"]
+  - if example.explanation?
     %p.explanation
-      = example["explanation"]
+      = example.explanation
 
-  - if example["parameters"]["data"].count > 0
+  - if example.parameters.present?
     %h3 Parameters
     %table.parameters
       %thead
         %tr
           %th Name
           %th Description
-          - example["parameters"]["extra_keys"].each do |key|
+          - example.parameters.extra_keys.each do |key|
             %th= key
       %tbody
-        - example["parameters"]["data"].each do |param|
+        - example.parameters.params.each do |param|
           %tr.parameter
-            %td{:class => ("required" if param["required"])}
-              - if param["scope"]
-                %span.name #{param['scope']}[#{param["name"]}]
+            %td{:class => ("required" if param.required?)}
+              - if param.scope?
+                %span.name #{param.scope}[#{param.name}]
               - else
-                %span.name= param["name"]
+                %span.name= param.name
             %td
-              %span.description= param["description"]
-            - example["parameters"]["extra_keys"].each do |key|
+              %span.description= param.description
+            - example.parameters.extra_keys.each do |key|
               %td
                 %span.extras= param[key]
 
+  - if example.response_fields.present?
+    %h3 Response Fields
+    %table.response-fields
+      %thead
+        %tr
+          %th Name
+          %th Description
+          - example.response_fields.extra_keys.each do |key|
+            %th= key
+      %tbody
+        - example.response_fields.fields.each do |field|
+          %tr.response-field
+            %td
+              - if field.scope?
+                %span.name #{field.scope}[#{field.name}]
+              - else
+                %span.name= field.name
+            %td
+              %span.description= field.description
+            - example.response_fields.extra_keys.each do |key|
+              %td
+                %span.extras= field[key]
 
-  - example["requests"].each_with_index do |request, index|
+  - example.requests.each_with_index do |request, index|
     .request{ :id => "request-#{index}" }
       %h3 Request
 
       %section.headers
         %h4 Headers
         %pre.headers
-          :ruby
-            # There are unwanted indents if this was a simple each and output in haml
-            headers = request["request_headers"].map do |header, value|
-              "#{header}: #{value}"
-            end
           :preserve
-            #{headers.join("\n")}
+            #{request.request_headers}
 
       %section.route
         %h4 Route
-        %pre.route.highlight== #{request["request_method"]} #{request["request_path"]}
+        %pre.route.highlight== #{request.request_method} #{request.request_path}
 
-      - if !request["request_query_parameters"].empty?
+      - if request.request_query_parameters?
         %section.query-parameters
           %h4 Query Parameters
           %pre.query-parameters.highlight
-            = request["request_query_parameters"].map { |k,v| "#{k}=#{v}" }.join("\n")
+            = request.request_query_parameters
 
-      - if request["request_body"]
+      - if request.request_body?
         %section.body
           %h4 Body
-          .content{ "data-content-type" => request["request_headers"]["Content-Type"] }
+          .content{ "data-content-type" => request.request_content_type }
             %textarea
               :preserve
-                #{request["request_body"]}
+                #{request.request_body}
 
-      - if request["curl"]
+      - if request.curl?
         %section.curl
           %h4 cURL
-          %pre= request["curl"]
+          %pre= request.curl
 
-      - if request["response_status"]
+      - if request.response?
         .response
           %h3 Response
 
           %section.headers
             %h4 Headers
             %pre.headers
-              :ruby
-                # There are unwanted indents if this was a simple each and output in haml
-                headers = request["response_headers"].map do |header, value|
-                  "#{header}: #{html_escape(value)}"
-                  end
               :preserve
-                #{headers.join("\n")}
+                #{request.response_headers}
 
           %section.status
             %h4 Status
-            %pre.status= request["response_status"]
+            %pre.status= request.response_status
 
-          - if request["response_body"]
+          - if request.response_body?
             %section.body
               %h4 Body
-              .content{ "data-content-type" => request["response_headers"]["Content-Type"] }
+              .content{ "data-content-type" => request.response_content_type }
                 %textarea
                   :preserve
-                    #{request["response_body"]}
+                    #{request.response_body}

data/lib/views/index.haml

@@ -1,9 +1,9 @@
 %h1= api_name
 
-- index["resources"].each do |resource|
+- index.resources.each do |resource|
   .resource
-    %h2= resource["name"]
+    %h2= resource.name
     %ul.examples
-      - resource["examples"].each do |example|
+      - resource.examples.each do |example|
         %li.example
-          = link_to example["description"], "/#{example["link"].gsub(".json", "")}"
+          = link_to example.description, "/#{example.href}"

data/lib/views/layout.haml

@@ -24,4 +24,8 @@
       }
   %body
     .container
-      = yield
+      .row-fluid
+        .span4.sidebar
+          = haml :nav, locals: { index: index, api_name: api_name }
+        .span8.main
+          = yield

data/lib/views/nav.haml

@@ -0,0 +1,8 @@
+
+- index.resources.each do |resource|
+  .resource
+    %b= resource.name
+    %ul.examples
+      - resource.examples.each do |example|
+        %li.example
+          = link_to example.description, "/#{example.href}"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: raddocs
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Eric Oestrich
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-21 00:00:00.000000000 Z
+date: 2015-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
@@ -76,20 +76,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.9'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.9.0
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.9'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.9.0
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rack-test
   requirement: !ruby/object:Gem::Requirement
@@ -97,9 +91,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.6.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -107,49 +98,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.6.1
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.1.2
+        version: '2.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.1.2
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.9.2.2
+        version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.9.2.2
+        version: '10.0'
 description: Browse documentation generated by the rspec_api_documentation gem
 email:
 - eric@oestrich.org
@@ -170,10 +146,11 @@ files:
 - lib/raddocs/app.rb
 - lib/raddocs/configuration.rb
 - lib/raddocs/middleware.rb
-- lib/raddocs/parameters.rb
+- lib/raddocs/models.rb
 - lib/views/example.haml
 - lib/views/index.haml
 - lib/views/layout.haml
+- lib/views/nav.haml
 homepage: http://github.com/oestrich/raddocs
 licenses:
 - MIT
@@ -194,8 +171,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.6
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.0
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: rspec_api_documentation browser
 test_files: []
+has_rdoc: 

data/lib/raddocs/parameters.rb

@@ -1,16 +0,0 @@
-module Raddocs
-  class Parameters
-    def initialize(params)
-      @params = params
-    end
-
-    def parse
-      extra_keys = @params.flat_map(&:keys).uniq - ["name", "description", "required", "scope"]
-
-      {
-        "extra_keys" => extra_keys,
-        "data" => @params
-      }
-    end
-  end
-end