grape_documenter 0.0.3 → 0.1.0

data/Guardfile

@@ -0,0 +1,24 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Rails example
+  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^app/(.*)(\.erb|\.haml)$})                 { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  watch('config/routes.rb')                           { "spec/routing" }
+  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
+
+  # Capybara request specs
+  watch(%r{^app/views/(.+)/.*\.(erb|haml)$})          { |m| "spec/requests/#{m[1]}_spec.rb" }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
+end
+

data/README.md

@@ -1,4 +1,4 @@
-# GrapeDoc
+# GrapeDocumenter
 
 This adds a task to Rails Applications to generate documentation for Grape APIs.
 
@@ -6,7 +6,7 @@ This adds a task to Rails Applications to generate documentation for Grape APIs.
 
 Add this line to your application's Gemfile:
 
-    gem 'grape_doc'
+    gem 'grape_documenter'
 
 And then execute:
 
@@ -14,13 +14,13 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install grape_doc
+    $ gem install grape_documenter
 
 ## Usage
 
 Within the root of you Rails Application run the following rake task...
 
-   $ bundle exec grape_doc 'MyApplication::API' '/path/to/where/you/want/your/docs'
+   $ bundle exec grape_documenter 'MyApplication::API' '/path/to/where/you/want/your/docs'
 
 The first argument is the a string of the class of Grape::API. If you have multiple APIs within the same application you can run the task as many times as you like with different output paths.
 

data/bin/{grape_doc → grape_documenter}

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-require 'grape_doc'
+require 'grape_documenter'
 
 begin
   require File.expand_path(Dir.pwd + "/config/environment")
@@ -8,5 +8,5 @@ rescue LoadError => ex
   puts "#{ex}"
 end
 
-generator = GrapeDoc::Generator.new(ARGV[0], ARGV[1], :format => ARGV[2])
+generator = GrapeDocumenter::Generator.new(ARGV[0], ARGV[1], :format => ARGV[2])
 generator.output

data/{grape_doc.gemspec → grape_documenter.gemspec}

@@ -1,5 +1,5 @@
 # -*- encoding: utf-8 -*-
-require File.expand_path('../lib/grape_doc/version', __FILE__)
+require File.expand_path('../lib/grape_documenter/version', __FILE__)
 
 Gem::Specification.new do |gem|
   gem.authors       = ["Phil Lee", "Steven Anderson"]
@@ -13,11 +13,13 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.name          = "grape_documenter"
   gem.require_paths = ["lib"]
-  gem.version       = GrapeDoc::VERSION
+  gem.version       = GrapeDocumenter::VERSION
 
   gem.add_dependency 'grape', '0.2.1'
   gem.add_dependency 'RedCloth'
   gem.add_dependency 'activesupport'
 
   gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'guard-rspec'
+  gem.add_development_dependency 'pry'
 end

data/lib/{grape_doc → grape_documenter}/formatters/html.rb

@@ -1,6 +1,6 @@
 require 'RedCloth'
 
-module GrapeDoc
+module GrapeDocumenter
   module Formatters
     # For ease this uses the textile formatter first then post processes to html
     class Html

data/lib/{grape_doc → grape_documenter}/formatters/textile.rb

@@ -1,6 +1,6 @@
 require 'active_support/core_ext/object/blank'
 
-module GrapeDoc
+module GrapeDocumenter
   module Formatters
     class Textile
       def initialize(structure)
@@ -17,20 +17,27 @@ module GrapeDoc
 
         doc.routes.each do |route|
           output << "\n\n"
-          output << "h2. #{route.route_method}: #{route.route_path.gsub(':version', doc.version)}"
+          output << "h2. #{route.http_method}: #{route.path.gsub(':version', doc.version)}"
           output << "\n\n"
 
-          if route.route_description.present?
+          if route.description.present?
             output << "h3. Description"
             output << "\n\n"
-            output << route.route_description
+            output << route.description
             output << "\n\n"
           end
 
-          if route.route_params.present?
+          if route.params.present?
             output << "h3. Parameters"
             output << "\n\n"
-            output << tabulate_params(route.route_params)
+            output << tabulate_params(route.params)
+            output << "\n\n"
+          end
+
+          if route.optional_params.present?
+            output << "h3. Optional Parameters"
+            output << "\n\n"
+            output << tabulate_params(route.optional_params)
             output << "\n\n"
           end
         end

data/lib/{grape_doc → grape_documenter}/generator.rb

@@ -1,7 +1,7 @@
 require 'fileutils'
 require 'active_support/inflector'
 
-module GrapeDoc
+module GrapeDocumenter
   class Generator
     def initialize(api_class, output_path, options = {})
       raise 'api_class must be specified' if api_class.nil?
@@ -79,7 +79,7 @@ module GrapeDoc
     end
 
     def routes_for_version_and_namespace(version, namespace)
-      routes_for_version(version).select { |r| normalize_route_namespace(r) == namespace }
+      routes_for_version(version).select { |r| normalize_route_namespace(r) == namespace }.map{|r| RouteDoc.new(r)}
     end
 
     def titleize(string)

data/lib/{grape_doc → grape_documenter}/namespace_doc.rb

@@ -1,6 +1,6 @@
-module GrapeDoc
+module GrapeDocumenter
   class NamespaceDoc
-    attr_accessor :title, :routes, :root_path, :version, :resources
+    attr_reader :title, :routes, :root_path, :version, :resources
 
     def initialize(options = {})
       @title = options[:title]

data/lib/{grape_doc → grape_documenter}/railtie.rb

@@ -1,6 +1,6 @@
-require 'grape_doc'
+require 'grape_documenter'
 
-module GrapeDoc
+module GrapeDocumenter
   class Railtie < Rails::Railtie
     rake_tasks do
       load 'tasks/generate.rake'

data/lib/grape_documenter/route_doc.rb

@@ -0,0 +1,27 @@
+module GrapeDocumenter
+  class RouteDoc
+    def initialize(route)
+      @route = route
+    end
+
+    def http_method
+      @route.route_method
+    end
+
+    def path
+      @route.route_path
+    end
+
+    def description
+      @route.route_description
+    end
+
+    def params
+      @route.route_params
+    end
+
+    def optional_params
+      @route.route_optional_params
+    end
+  end
+end

data/lib/grape_documenter/version.rb

@@ -0,0 +1,3 @@
+module GrapeDocumenter
+  VERSION = "0.1.0"
+end

data/lib/{grape_doc → grape_documenter}/writer.rb

@@ -1,4 +1,4 @@
-module GrapeDoc
+module GrapeDocumenter
   class Writer
     def initialize(doc_structure)
       @doc_structure = doc_structure

data/lib/grape_documenter.rb

@@ -0,0 +1,11 @@
+require "grape_documenter/version"
+
+module GrapeDocumenter
+  require 'grape_documenter/generator'
+  require 'grape_documenter/writer'
+  require 'grape_documenter/namespace_doc'
+  require 'grape_documenter/route_doc'
+  require 'grape_documenter/formatters/textile'
+  require 'grape_documenter/formatters/html'
+  require 'grape_documenter/railtie' if defined?(Rails)
+end

data/lib/tasks/generate.rake

@@ -1,7 +1,7 @@
-require 'grape_doc'
+require 'grape_documenter'
 
 desc "Generate documentation for Grape API"
 task :generate_grape_docs, [:api_class, :output_path, :format] => :environment do |t, args|
-  generator = GrapeDoc::Generator.new(args[:api_class], args[:output_path], :format => args[:format])
+  generator = GrapeDocumenter::Generator.new(args[:api_class], args[:output_path], :format => args[:format])
   generator.output
 end

data/spec/formatters/textile_spec.rb

@@ -1,18 +1,19 @@
 require 'spec_helper'
 
-describe GrapeDoc::Formatters::Textile do
+describe GrapeDocumenter::Formatters::Textile do
   let(:mock_route) do
     mock('route', :route_method => 'GET',
                   :route_path => '/users',
                   :route_description => 'users description goes here',
-                  :route_params => {:id => {:type => 'integer', :desc => 'user id'}})
+                  :route_params => {'id' => {:type => 'integer', :desc => 'user id'}},
+                  :route_optional_params => {'foo' => {:type => 'string', :desc => 'fooness'}})
   end
 
   let(:structure) do
-    GrapeDoc::NamespaceDoc.new :version => 'v1',
+    GrapeDocumenter::NamespaceDoc.new :version => 'v1',
         :title => 'Users',
         :root_path => '/users',
-        :routes => [mock_route],
+        :routes => [GrapeDocumenter::RouteDoc.new(mock_route)],
         :resources => [{ :name => 'Contacts', :path => '/contacts' }]
   end
 
@@ -31,9 +32,15 @@ describe GrapeDoc::Formatters::Textile do
     subject.format.should include('users description goes here')
   end
 
-  it 'has an h3 and the route_params in a table' do
+  it 'has an h3 and the params in a table' do
     subject.format.should include('h3. Parameters')
     subject.format.should include('|_.Name|_.Type|_.Description|')
     subject.format.should include('|id|integer|user id|')
   end
+
+  it 'has an h3 and the optional_params in a table' do
+    subject.format.should include('h3. Optional Parameters')
+    subject.format.should include('|_.Name|_.Type|_.Description|')
+    subject.format.should include('|foo|string|fooness|')
+  end
 end

data/spec/generator_spec.rb

@@ -1,27 +1,53 @@
 require 'spec_helper'
 
-describe GrapeDoc::Generator do
-  subject { described_class.new 'MyApplication::API', '/tmp/grape_doc' }
+describe GrapeDocumenter::Generator do
+  subject { described_class.new 'MyApplication::API', '/tmp/grape_documenter' }
 
-  context 'for a given api version' do
-    it 'stores the version' do
-      subject.generate_namespace_docs.first.version.should == 'v1'
-    end
+  context 'integration test' do
+    context 'for the first api version' do
+      it 'stores the version' do
+        subject.generate_namespace_docs.first.version.should == 'v1'
+      end
 
-    it 'stores the title' do
-      subject.generate_namespace_docs.first.title.should == 'User'
-    end
+      it 'stores the title' do
+        subject.generate_namespace_docs.first.title.should == 'User'
+      end
 
-    it 'stores the root_path' do
-      subject.generate_namespace_docs.first.root_path.should == '/user'
-    end
+      it 'stores the root_path' do
+        subject.generate_namespace_docs.first.root_path.should == '/user'
+      end
 
-    it 'stores the routes' do
-      subject.generate_namespace_docs.first.routes.should == MyApplication::API.routes.select{|r| r.route_version == 'v1'}
-    end
+      describe 'routes' do
+        let(:routes) { subject.generate_namespace_docs.first.routes }
+
+        describe 'index' do
+          describe 'description' do
+            it 'returns Get all users' do
+              routes.first.description.should == 'Get all users'
+            end
+          end
+        end
+
+        describe 'show' do
+          describe 'params' do
+            it 'returns id with desc and type' do
+              routes[1].params.should == { 'id' => { :desc => 'The id of the user', :type => 'integer' } }
+            end
+          end
+        end
+
+        describe 'post' do
+          describe 'optional params' do
+            it 'returns first_name with desc and type' do
+              routes[2].optional_params.should == { 'first_name' => { :desc => 'First name of the user', :type => 'string' } }
+            end
+          end
+        end
+      end
 
-    it 'stores the global resources' do
-      subject.generate_namespace_docs.first.resources.should == [{ :name => 'User', :path => '/user' }]
+      it 'stores the global resources' do
+        subject.generate_namespace_docs.first.resources.should == [{ :name => 'User', :path => '/user' }]
+      end
     end
   end
 end

data/spec/namespace_doc_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+describe GrapeDocumenter::NamespaceDoc do
+  describe 'attrubutes' do
+    subject do
+      described_class.new :title => 'some title',
+                          :routes => 'some routes',
+                          :root_path => 'some root path',
+                          :version => 'some version',
+                          :resources => 'some resources'
+    end
+
+    it 'stores title' do
+      subject.title.should == 'some title'
+    end
+
+    it 'stores routes' do
+      subject.routes.should == 'some routes'
+    end
+
+    it 'stores root_path' do
+      subject.root_path.should == 'some root path'
+    end
+
+    it 'stores version' do
+      subject.version.should == 'some version'
+    end
+
+    it 'stores resources' do
+      subject.resources.should == 'some resources'
+    end
+  end
+end

data/spec/route_doc_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+
+describe GrapeDocumenter::RouteDoc do
+  let(:mock_route) do
+    mock('route', :route_method => 'GET',
+                  :route_path => '/users',
+                  :route_description => 'users description goes here',
+                  :route_params => {'id' => {:type => 'integer', :desc => 'user id'}},
+                  :route_optional_params => {'foo' => {:type => 'string', :desc => 'fooness'}})
+  end
+
+  subject { described_class.new mock_route  }
+
+  describe 'attributes' do
+    it 'returns the method' do
+      # cant use #method as reserved word
+      subject.http_method.should == 'GET'
+    end
+
+    it 'returns the path' do
+      subject.path.should == '/users'
+    end
+
+    it 'returns the description' do
+      subject.description.should == 'users description goes here'
+    end
+
+    it 'returns the params' do
+      subject.params.should == {'id' => {:type => 'integer', :desc => 'user id'}}
+    end
+
+    it 'returns the params' do
+      subject.optional_params.should == {'foo' => {:type => 'string', :desc => 'fooness'}}
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,2 +1,2 @@
-require 'grape_doc'
+require 'grape_documenter'
 require 'support/test_api'

data/spec/support/test_api.rb

@@ -13,6 +13,14 @@ module MyApplication
         }
         get ':id' do
         end
+
+        post '/', {
+          :params => {
+            'username' => { :desc => 'The username of the user', :type => 'string' }
+          }, :optional_params => {
+            'first_name' => { :desc => 'First name of the user', :type => 'string' }
+          }
+        }
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: grape_documenter
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-15 00:00:00.000000000 Z
+date: 2012-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -76,33 +76,69 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  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'
+- !ruby/object:Gem::Dependency
+  name: pry
+  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: This adds a task to Rails Applications to generate documentation for
   Grape APIs.
 email:
 - philip.lee@sage.com
 executables:
-- grape_doc
+- grape_documenter
 extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
 - Gemfile
+- Guardfile
 - LICENSE
 - README.md
 - Rakefile
-- bin/grape_doc
-- grape_doc.gemspec
-- lib/grape_doc.rb
-- lib/grape_doc/formatters/html.rb
-- lib/grape_doc/formatters/textile.rb
-- lib/grape_doc/generator.rb
-- lib/grape_doc/namespace_doc.rb
-- lib/grape_doc/railtie.rb
-- lib/grape_doc/version.rb
-- lib/grape_doc/writer.rb
+- bin/grape_documenter
+- grape_documenter.gemspec
+- lib/grape_documenter.rb
+- lib/grape_documenter/formatters/html.rb
+- lib/grape_documenter/formatters/textile.rb
+- lib/grape_documenter/generator.rb
+- lib/grape_documenter/namespace_doc.rb
+- lib/grape_documenter/railtie.rb
+- lib/grape_documenter/route_doc.rb
+- lib/grape_documenter/version.rb
+- lib/grape_documenter/writer.rb
 - lib/tasks/generate.rake
 - spec/formatters/textile_spec.rb
 - spec/generator_spec.rb
+- spec/namespace_doc_spec.rb
+- spec/route_doc_spec.rb
 - spec/spec_helper.rb
 - spec/support/test_api.rb
 homepage: ''
@@ -125,7 +161,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: This adds a task to Rails Applications to generate documentation for Grape
@@ -133,6 +169,7 @@ summary: This adds a task to Rails Applications to generate documentation for Gr
 test_files:
 - spec/formatters/textile_spec.rb
 - spec/generator_spec.rb
+- spec/namespace_doc_spec.rb
+- spec/route_doc_spec.rb
 - spec/spec_helper.rb
 - spec/support/test_api.rb
-has_rdoc: 

data/lib/grape_doc/version.rb

@@ -1,3 +0,0 @@
-module GrapeDoc
-  VERSION = "0.0.3"
-end

data/lib/grape_doc.rb

@@ -1,10 +0,0 @@
-require "grape_doc/version"
-
-module GrapeDoc
-  require 'grape_doc/generator'
-  require 'grape_doc/writer'
-  require 'grape_doc/namespace_doc'
-  require 'grape_doc/formatters/textile'
-  require 'grape_doc/formatters/html'
-  require 'grape_doc/railtie' if defined?(Rails)
-end