rspec_api_documentation 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7cbc2ff27b6b9f2442e946657e47fc88c2c3e6ee
-  data.tar.gz: a8f1639743ba2ecfed6c625231ecc3506c025d25
+  metadata.gz: b7e6c19ee26d9e8b093eda724140422fd0752308
+  data.tar.gz: 852e00b740d884e07466feebfbfbf34dd98b18f4
 SHA512:
-  metadata.gz: f84d994ca272c1802358f4aa89d0549af42fa03f8fc8abc840e229ac1f74d828cd9758bb8d5e541b6314f75cefe6639390ad2b979ea889469178a040be70c50e
-  data.tar.gz: d3f198afe1676a8abbadf41dfa8de83192128bed0dd293691cfeeded33766b7a0e08fff1fa2188a164c85da86cd218924bc27591e9206048c764c4508f508100
+  metadata.gz: b84b411b63bae9373d07dd30040a9c2dc64d789b6718d84da867f3774bb2a54731aa67fb2d5a530a1332d4562f3055e021e27c9087434de5b1c6be820fc02675
+  data.tar.gz: 6e994149dcb0875ca38ec9d6ad9a26d6f86e879294ffba13b5c1b4da4dc3f08b3ad37aec69cdc10c3e8baf44369b6284a5024cbaf5589e99c19893fb35c75c7b

data/lib/rspec_api_documentation.rb

@@ -3,6 +3,7 @@ require 'active_support/inflector'
 require 'cgi'
 require 'json'
 
+# Namespace for RspecApiDocumentation
 module RspecApiDocumentation
   extend ActiveSupport::Autoload
 
@@ -32,6 +33,7 @@ module RspecApiDocumentation
     autoload :GeneralMarkupWriter
     autoload :HtmlWriter
     autoload :TextileWriter
+    autoload :MarkdownWriter
     autoload :JsonWriter
     autoload :AppendJsonWriter
     autoload :JsonIodocsWriter
@@ -49,6 +51,8 @@ module RspecApiDocumentation
     autoload :HtmlExample
     autoload :TextileIndex
     autoload :TextileExample
+    autoload :MarkdownIndex
+    autoload :MarkdownExample
   end
 
   def self.configuration
@@ -59,6 +63,13 @@ module RspecApiDocumentation
     @documentations ||= configuration.map { |config| ApiDocumentation.new(config) }
   end
 
+  # Configures RspecApiDocumentation
+  #
+  # See RspecApiDocumentation::Configuration for more information on configuring.
+  #
+  #   RspecApiDocumentation.configure do |config|
+  #     config.docs_dir = "doc/api"
+  #   end
   def self.configure
     yield configuration if block_given?
   end

data/lib/rspec_api_documentation/client_base.rb

@@ -1,4 +1,7 @@
 module RspecApiDocumentation
+  # Base client class that documents all requests that go through it.
+  #
+  #  client.get("/orders", { :page => 2 }, { "Accept" => "application/json" })
   class ClientBase < Struct.new(:context, :options)
     include Headers
 

data/lib/rspec_api_documentation/configuration.rb

@@ -13,6 +13,23 @@ module RspecApiDocumentation
       @groups ||= []
     end
 
+    # Defines a new sub configuration
+    #
+    # Automatically sets the `filter` to the group name, and the `docs_dir` to
+    # a subfolder of the parent's `doc_dir` named the group name.
+    #
+    #   RspecApiDocumentation.configure do |config|
+    #     config.docs_dir = "doc/api"
+    #     config.define_group(:public) do |config|
+    #       # Default values
+    #       config.docs_dir = "doc/api/public"
+    #       config.filter = :public
+    #     end
+    #   end
+    #
+    # Params:
+    # +name+:: String name of the group
+    # +block+:: Block configuration block
     def define_group(name, &block)
       subconfig = self.class.new(self)
       subconfig.filter = name
@@ -79,6 +96,7 @@ module RspecApiDocumentation
       @settings ||= {}
     end
 
+    # Yields itself and sub groups to hook into the Enumerable module
     def each(&block)
       yield self
       groups.map { |g| g.each &block }

data/lib/rspec_api_documentation/dsl.rb

@@ -2,6 +2,16 @@ require "rspec_api_documentation/dsl/resource"
 require "rspec_api_documentation/dsl/endpoint"
 require "rspec_api_documentation/dsl/callback"
 
+# Custom describe block that sets metadata to enable the rest of RAD
+#
+#   resource "Orders", :meta => :data do
+#     # ...
+#   end
+#
+# Params:
+# +args+:: Glob of RSpec's `describe` arguments
+# +block+:: Block to pass into describe
+#
 def self.resource(*args, &block)
   options = if args.last.is_a?(Hash) then args.pop else {} end
   options[:api_doc_dsl] = :resource

data/lib/rspec_api_documentation/dsl/callback.rb

@@ -1,4 +1,5 @@
 module RspecApiDocumentation::DSL
+  # DSL Methods for testing server callbacks
   module Callback
     extend ActiveSupport::Concern
 

data/lib/rspec_api_documentation/dsl/endpoint.rb

@@ -3,6 +3,7 @@ require 'rack/utils'
 require 'rack/test/utils'
 
 module RspecApiDocumentation::DSL
+  # DSL methods available inside the RSpec example.
   module Endpoint
     extend ActiveSupport::Concern
     include Rack::Test::Utils
@@ -23,6 +24,7 @@ module RspecApiDocumentation::DSL
       end
 
       private
+
       # from rspec-core
       def relative_path(line)
         line = line.sub(File.expand_path("."), ".")

data/lib/rspec_api_documentation/dsl/resource.rb

@@ -1,4 +1,5 @@
 module RspecApiDocumentation::DSL
+  # DSL methods available at the example group level
   module Resource
     extend ActiveSupport::Concern
 

data/lib/rspec_api_documentation/views/markdown_example.rb

@@ -0,0 +1,16 @@
+module RspecApiDocumentation
+  module Views
+    class MarkdownExample < MarkupExample
+      EXTENSION = 'markdown'
+
+      def initialize(example, configuration)
+        super
+        self.template_name = "rspec_api_documentation/markdown_example"
+      end
+
+      def extension
+        EXTENSION
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/views/markdown_index.rb

@@ -0,0 +1,14 @@
+module RspecApiDocumentation
+  module Views
+    class MarkdownIndex < MarkupIndex
+      def initialize(index, configuration)
+        super
+        self.template_name = "rspec_api_documentation/markdown_index"
+      end
+
+      def examples
+        @index.examples.map { |example| MarkdownExample.new(example, @configuration) }
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/writers/combined_json_writer.rb

@@ -3,7 +3,7 @@ require 'rspec_api_documentation/writers/json_writer'
 module RspecApiDocumentation
   module Writers
     class CombinedJsonWriter < Writer
-      def self.write(index, configuration)
+      def write
         File.open(configuration.docs_dir.join("combined.json"), "w+") do |f|
           examples = []
           index.examples.each do |rspec_example|

data/lib/rspec_api_documentation/writers/combined_text_writer.rb

@@ -1,7 +1,7 @@
 module RspecApiDocumentation
   module Writers
     class CombinedTextWriter < Writer
-      def self.write(index, configuration)
+      def write
         index.examples.each do |rspec_example|
           example = CombinedTextExample.new(rspec_example)
           FileUtils.mkdir_p(configuration.docs_dir.join(example.resource_name))

data/lib/rspec_api_documentation/writers/general_markup_writer.rb

@@ -1,8 +1,10 @@
 module RspecApiDocumentation
   module Writers
+    # Base class for writers that write HTML
     class GeneralMarkupWriter < Writer
       INDEX_FILE_NAME = 'index'
 
+      # Write out the generated documentation
       def write
         File.open(configuration.docs_dir.join(index_file_name + '.' + extension), "w+") do |f|
           f.write markup_index_class.new(index, configuration).render

data/lib/rspec_api_documentation/writers/markdown_writer.rb

@@ -0,0 +1,19 @@
+module RspecApiDocumentation
+  module Writers
+    class MarkdownWriter < GeneralMarkupWriter
+      EXTENSION = 'markdown'
+
+      def markup_index_class
+        RspecApiDocumentation::Views::MarkdownIndex
+      end
+
+      def markup_example_class
+        RspecApiDocumentation::Views::MarkdownExample
+      end
+
+      def extension
+        EXTENSION
+      end
+    end
+  end
+end

data/templates/rspec_api_documentation/markdown_example.mustache

@@ -0,0 +1,68 @@
+# {{ resource_name }} API
+
+## {{ description }}
+
+### {{ http_method }} {{ route }}
+
+{{# explanation }}
+{{ explanation }}
+{{/ explanation }}
+
+{{# has_parameters? }}
+### Parameters
+{{# parameters }}
+
+Name : {{ name }} {{# required }} *- required -*{{/ required }}
+Description : {{ description }}
+{{/ parameters }}
+{{/ has_parameters? }}
+
+{{# requests }}
+### Request
+
+#### Headers
+
+<pre>{{ request_headers_text }}</pre>
+
+#### Route
+
+<pre>{{ request_method }} {{ request_path }}</pre>
+
+{{# request_query_parameters_text }}
+#### Query Parameters
+
+<pre>{{ request_query_parameters_text }}</pre>
+{{/ request_query_parameters_text }}
+
+{{# request_body }}
+#### Body
+
+<pre>{{{ request_body }}}</pre>
+{{/ request_body }}
+
+{{# curl }}
+#### cURL
+
+<pre class="request">{{ curl }}</pre>
+{{/ curl }}
+
+{{# response_status }}
+### Response
+
+#### Headers
+
+<pre>{{ response_headers_text }}</pre>
+
+#### Status
+
+<pre>{{ response_status }} {{ response_status_text}}</pre>
+
+{{# response_body }}
+#### Body
+
+<pre>{{{ response_body }}}</pre>
+{{/ response_body }}
+{{/ response_status }}
+
+{{/ requests }}
+

data/templates/rspec_api_documentation/markdown_index.mustache

@@ -0,0 +1,10 @@
+# {{ api_name }}
+
+{{# sections }}
+## {{ resource_name }}
+
+{{# examples }}
+* [{{ description }}]({{ dirname }}/{{ filename }})
+{{/ examples }}
+
+{{/ sections }}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec_api_documentation
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Chris Cahoon
@@ -10,188 +10,194 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-15 00:00:00.000000000 Z
+date: 2014-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.14.0
+    - - ">="
       - !ruby/object:Gem::Version
         version: 2.14.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.14.0
+    - - ">="
       - !ruby/object:Gem::Version
         version: 2.14.0
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: i18n
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: mustache
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.99.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.99.4
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.4.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.4.6
 - !ruby/object:Gem::Dependency
   name: fakefs
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: sinatra
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: aruba
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rack-test
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.6.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.6.2
 - !ruby/object:Gem::Dependency
   name: rack-oauth2
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.14.4
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.14.4
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.7.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.7.0
 description: Generate API docs from your test suite
@@ -204,44 +210,49 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/rspec_api_documentation.rb
-- lib/tasks/docs.rake
-- lib/rspec_api_documentation/rack_test_client.rb
+- lib/rspec_api_documentation/api_documentation.rb
 - lib/rspec_api_documentation/api_formatter.rb
+- lib/rspec_api_documentation/client_base.rb
+- lib/rspec_api_documentation/configuration.rb
 - lib/rspec_api_documentation/curl.rb
-- lib/rspec_api_documentation/index.rb
-- lib/rspec_api_documentation/headers.rb
-- lib/rspec_api_documentation/oauth2_mac_client.rb
+- lib/rspec_api_documentation/dsl.rb
 - lib/rspec_api_documentation/dsl/callback.rb
 - lib/rspec_api_documentation/dsl/endpoint.rb
 - lib/rspec_api_documentation/dsl/resource.rb
-- lib/rspec_api_documentation/dsl.rb
+- lib/rspec_api_documentation/example.rb
+- lib/rspec_api_documentation/headers.rb
+- lib/rspec_api_documentation/index.rb
+- lib/rspec_api_documentation/oauth2_mac_client.rb
+- lib/rspec_api_documentation/rack_test_client.rb
+- lib/rspec_api_documentation/railtie.rb
+- lib/rspec_api_documentation/test_server.rb
 - lib/rspec_api_documentation/views/html_example.rb
 - lib/rspec_api_documentation/views/html_index.rb
+- lib/rspec_api_documentation/views/markdown_example.rb
+- lib/rspec_api_documentation/views/markdown_index.rb
+- lib/rspec_api_documentation/views/markup_example.rb
+- lib/rspec_api_documentation/views/markup_index.rb
 - lib/rspec_api_documentation/views/textile_example.rb
 - lib/rspec_api_documentation/views/textile_index.rb
-- lib/rspec_api_documentation/views/markup_index.rb
-- lib/rspec_api_documentation/views/markup_example.rb
 - lib/rspec_api_documentation/writers/append_json_writer.rb
-- lib/rspec_api_documentation/writers/textile_writer.rb
+- lib/rspec_api_documentation/writers/combined_json_writer.rb
+- lib/rspec_api_documentation/writers/combined_text_writer.rb
+- lib/rspec_api_documentation/writers/formatter.rb
 - lib/rspec_api_documentation/writers/general_markup_writer.rb
 - lib/rspec_api_documentation/writers/html_writer.rb
-- lib/rspec_api_documentation/writers/json_iodocs_writer.rb
 - lib/rspec_api_documentation/writers/index_helper.rb
+- lib/rspec_api_documentation/writers/json_iodocs_writer.rb
 - lib/rspec_api_documentation/writers/json_writer.rb
+- lib/rspec_api_documentation/writers/markdown_writer.rb
+- lib/rspec_api_documentation/writers/textile_writer.rb
 - lib/rspec_api_documentation/writers/writer.rb
-- lib/rspec_api_documentation/writers/combined_json_writer.rb
-- lib/rspec_api_documentation/writers/formatter.rb
-- lib/rspec_api_documentation/writers/combined_text_writer.rb
-- lib/rspec_api_documentation/configuration.rb
-- lib/rspec_api_documentation/example.rb
-- lib/rspec_api_documentation/api_documentation.rb
-- lib/rspec_api_documentation/test_server.rb
-- lib/rspec_api_documentation/railtie.rb
-- lib/rspec_api_documentation/client_base.rb
-- templates/rspec_api_documentation/textile_example.mustache
+- lib/tasks/docs.rake
+- templates/rspec_api_documentation/html_example.mustache
 - templates/rspec_api_documentation/html_index.mustache
+- templates/rspec_api_documentation/markdown_example.mustache
+- templates/rspec_api_documentation/markdown_index.mustache
+- templates/rspec_api_documentation/textile_example.mustache
 - templates/rspec_api_documentation/textile_index.mustache
-- templates/rspec_api_documentation/html_example.mustache
 homepage: http://smartlogicsolutions.com
 licenses:
 - MIT
@@ -252,18 +263,19 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.3.6
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: A double black belt for your docs
 test_files: []
+has_rdoc: