restapi_doc 0.0.1

data/Gemfile

@@ -0,0 +1,11 @@
+source 'http://rubygems.org'
+
+gem 'activesupport', '>= 2.1'
+gem 'haml', '3.1.4'
+
+group :development do
+  gem 'rake'
+  gem 'jeweler'
+  gem 'rspec', '>= 2.2.0'
+  gem 'mocha'
+end

data/Gemfile.lock

@@ -0,0 +1,36 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    haml (3.1.4)
+    jeweler (1.8.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.6.6)
+    metaclass (0.0.1)
+    mocha (0.11.3)
+      metaclass (~> 0.0.1)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.9.0)
+      rspec-core (~> 2.9.0)
+      rspec-expectations (~> 2.9.0)
+      rspec-mocks (~> 2.9.0)
+    rspec-core (2.9.0)
+    rspec-expectations (2.9.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.9.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  haml (= 3.1.4)
+  jeweler
+  mocha
+  rake
+  rspec (>= 2.2.0)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Kevin Haight (kevinjhaight@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,28 @@
+= Rest Api Doc
+
+Rest API doc generates an easy way to create a Twitter style document for your RESTful interface
+
+Leveraging Twitter Bootstrap to create an easy to read document for your RESTful api.
+
+== Installing the gem
+	
+        gem install restapi_doc
+
+== Set Up
+Run the following rake command to setup your environment.
+
+        rake restapi_doc:generate
+		
+This will create a 'restapi_doc' directory in your Rails config directory.
+In this directory you will now have a "restapi_doc.yml' file with some simple configuration options for your API document.
+
+
+== Documenting controllers
+Below is a sample of how to document the controller to generate a document
+
+
+== Creating Api Document
+
+        rake restapi_doc:generate
+		
+You will now have a 'apidoc' directory located in your Rails 'public' directory

data/Rakefile

@@ -0,0 +1,39 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "restapi_doc"
+    gem.summary = %Q{REST API doc generates an easy way to create a twitter style document for your RESTful interface}
+    gem.description = %Q{REST API doc generates an easy way to create a twitter style document for your RESTful interface.  
+                        Leveraging Twitter Bootstrap to create an easy to read document for your RESTful api. }
+    gem.email = "kevinjhaight@gmail.com"
+    gem.homepage = "http://github.com/alayho/restapi_doc"
+    gem.authors = ["Kevin Haight"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "restapi_doc #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/restapi_doc/config/restapi_doc.yml

@@ -0,0 +1,2 @@
+project_name: "RESTful API"
+base_url: "http://api.mydomain.com"

data/lib/restapi_doc/config.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+module RestApiDoc
+  module Config
+    def template_dir(f = nil)
+      @template_dir ||= File.join(File.dirname(__FILE__), 'template')
+      form_file_name @template_dir, f
+    end
+    
+    def config_template_dir(f = nil)
+      @template_dir ||= File.join(File.dirname(__FILE__), 'config')
+      form_file_name @template_dir, f
+    end
+    
+    def asset_dir
+      @asset_dir ||= File.join(File.dirname(__FILE__), 'template/assets')
+    end
+
+    def config_dir(f = nil)
+      @config_dir ||= File.join(::Rails.root.to_s, 'config/restapi_doc')
+      form_file_name @config_dir, f
+    end
+
+    def target_dir(f = nil)
+      @target_dir ||= File.join(::Rails.root.to_s, 'public/apidoc/')
+      form_file_name @target_dir, f 
+    end
+
+    def controller_dir(f = nil)
+      @controller_dir ||= File.join(::Rails.root.to_s, 'app/controllers/')
+      form_file_name @controller_dir, f
+    end
+
+    def temp_dir(f = nil)
+      @temp_dir ||= "#{Dir.mktmpdir("apidoc")}/"
+      form_file_name @temp_dir, f
+    end
+
+    def form_file_name(dir, file)
+      case file
+      when NilClass then dir
+      when String then File.join(dir, file)
+      else raise ArgumentError, "Invalid argument #{file}"
+      end
+    end
+  end
+end

data/lib/restapi_doc/method_doc.rb

@@ -0,0 +1,84 @@
+# encoding: utf-8
+module RestApiDoc
+  class MethodDoc
+    attr_accessor :scope, :method_order, :content, :request, :response, :output, :params, :defname, :response_formats, :requires_authentication, :request_url,  :account_password_required, :http_responses
+    
+    def initialize(resource_name, type, order)
+      @resource_name = resource_name
+      @scope = type
+      @method_order = order
+      @content = ""
+      @request = ""
+      @response = ""
+      @output = ""
+      @params = []
+      @response_formats = []
+      @http_responses= []
+      @requires_authentication = "No"
+      @account_password_required = "No"
+      @defname = nil
+      @request_url = nil
+    end
+
+    def process_line(line, current_scope)
+      new_scope = current_scope
+      case current_scope
+      when :response
+        if line =~ /::response-end::/
+          new_scope = :function
+        else
+          @response << line
+        end
+      when :request
+        if line =~ /::request-end::/
+          new_scope = :function
+        else
+          @request << line
+        end
+      when :output # append output
+        if line =~ /::output-end::/
+          new_scope = :function
+        else
+          @output << line
+        end
+      when :class, :function
+        result = line.scan(/(\w+)\:\:\s*(.+)/)
+        if not result.empty?
+          key, value = result[0]
+          case key
+          when "response", "request"
+            new_scope = key.to_sym
+          when "output"
+            new_scope = key.to_sym
+          when "param"
+            @params << value
+          when "http_response"
+            @http_responses << value
+          when "response_format"
+            @response_formats << value
+          when "requires_authentication"
+            @requires_authentication = value
+          when "request_url"
+            @request_url = value
+          when "account_password_required"
+            @account_password_required = value
+          else # user wants this new shiny variable whose name is the key with value = value
+            instance_variable_set("@#{key}".to_sym, value)
+            define_singleton_method(key.to_sym) { value } # define accessor for the templates to read it
+          end
+        else
+          # add line to block
+          @content << line
+        end
+      else
+        raise ParsingException, "logic error: unknown current scope #{current_scope}"
+      end
+      new_scope
+    end
+
+    def get_binding
+      binding
+    end
+
+  end
+end

data/lib/restapi_doc/railtie.rb

@@ -0,0 +1,9 @@
+# encoding: utf-8
+require 'rails'
+module RestApiDoc
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load 'restapi_doc/tasks/restapi_doc_tasks.rake'
+    end
+  end
+end

data/lib/restapi_doc/resource_doc.rb

@@ -0,0 +1,104 @@
+# encoding: utf-8
+require_relative 'method_doc'
+
+module RestApiDoc
+  class ParsingException < Exception;
+  end
+  class ResourceDoc
+
+    attr_reader :name, :resource_location, :controller_name, :class_block, :function_blocks, :resource_header, :resource_methods, :description
+
+    # Initializes ResourceDoc.
+    def initialize(name, action_methods, controller_location, options = {})
+      @name = name
+      @class_block = nil
+      @function_blocks = []
+      @resource_methods = action_methods
+      @resource_header = ""
+      @standard_methods = options[:standard_methods] || [:put, :post, :get, :delete]
+      @resource_location = resource_location
+      @controller_location = controller_location
+      @description = nil
+      @controller_name = File.basename(controller_location)
+    end
+
+    # parse the controller
+    def parse_apidoc
+      lines = IO.readlines(@controller_location)
+      begin
+        @class_block, @function_blocks = ResourceDoc.parse_controller_doc(@name, lines)
+      rescue ParsingException => ex
+        puts "error #{ex} while parsing #{@controller_location}"
+        exit
+      end
+      if !@class_block.nil?
+        @description = @class_block.content
+      end
+      
+      @resource_methods.each do | req_m |
+          req_m << @function_blocks.select{|f| f.defname == req_m[0]}.first
+      end
+    end
+
+    # This method parses the doc
+    def self.parse_controller_doc(name, lines)
+      current_api_block = nil
+      current_scope = :none
+      in_class = false
+      class_block = nil
+      function_blocks = []
+      order = 1
+      lines.each_with_index do |line, line_no|
+        line.gsub!(/^ *#/, '') # strip the starting '#' on the line
+        case line
+          when /=begin apidoc/
+            # if we get apidoc tag inside class definition, then they are for a method
+            current_scope = !in_class ? :class : :function
+            current_api_block = MethodDoc.new(name, current_scope, order)
+          when /=end/
+            if current_api_block.nil?
+              raise ParsingException, "#{line_no} - No starttag for '=end' found"
+            end
+          when /class/ # keep track of whether a resource or an api is being annotated
+            in_class = true
+            if !current_api_block.nil?
+            case current_scope
+              when :class
+                class_block = current_api_block
+              when :function
+                function_blocks << current_api_block
+              else
+                raise ParsingException, "logic error: unknown current scope #{current_scope}"
+            end
+            
+            current_api_block = nil
+            current_scope = :none
+            order += 1
+          end
+          when /def/
+            if !current_api_block.nil?
+              current_api_block.defname = line.gsub('def ', '').strip
+              
+              case current_scope
+                when :class
+                  class_block = current_api_block
+                when :function
+                  function_blocks << current_api_block
+                else
+                  raise ParsingException, "logic error: unknown current scope #{current_scope}"
+              end
+              
+              current_api_block = nil
+              current_scope = :none
+              order += 1
+            end
+          else
+            if current_api_block # process lines only if they are apidoc comments
+              current_scope = current_api_block.process_line(line, current_scope)
+            end
+        end
+      end
+      [class_block, function_blocks]
+    end
+  end
+end

data/lib/restapi_doc/tasks/restapi_doc_tasks.rake

@@ -0,0 +1,28 @@
+# encoding: utf-8
+include RestApiDoc
+
+namespace :restapi_doc do
+
+  desc "Generate the config files"
+  task :setup do
+    create_structure
+  end
+
+  desc "Generate the api documentation"
+  task :generate do
+    remove_structure
+    resources = get_resources do |controller, controller_url, controller_location|
+    end
+    if !resources.empty?
+      puts "Generating API documentation..."
+      generate_doc(resources)
+      move_document
+      puts "Completed API documentation generation"
+    end
+  end
+  
+  desc "Generate the config files"
+  task :clean do
+    remove_structure
+  end
+end

data/lib/restapi_doc/template/assets/css/bootstrap-responsive.min.css

@@ -0,0 +1,12 @@
+.clearfix{*zoom:1;}.clearfix:before,.clearfix:after{display:table;content:"";}
+.clearfix:after{clear:both;}
+.hide-text{overflow:hidden;text-indent:100%;white-space:nowrap;}
+.input-block-level{display:block;width:100%;min-height:28px;-webkit-box-sizing:border-box;-moz-box-sizing:border-box;-ms-box-sizing:border-box;box-sizing:border-box;}
+.hidden{display:none;visibility:hidden;}
+.visible-phone{display:none;}
+.visible-tablet{display:none;}
+.visible-desktop{display:block;}
+.hidden-phone{display:block;}
+.hidden-tablet{display:block;}
+.hidden-desktop{display:none;}
+@media (max-width:767px){.visible-phone{display:block;} .hidden-phone{display:none;} .hidden-desktop{display:block;} .visible-desktop{display:none;}}@media (min-width:768px) and (max-width:979px){.visible-tablet{display:block;} .hidden-tablet{display:none;} .hidden-desktop{display:block;} .visible-desktop{display:none;}}@media (max-width:480px){.nav-collapse{-webkit-transform:translate3d(0, 0, 0);} .page-header h1 small{display:block;line-height:18px;} input[type="checkbox"],input[type="radio"]{border:1px solid #ccc;} .form-horizontal .control-group>label{float:none;width:auto;padding-top:0;text-align:left;} .form-horizontal .controls{margin-left:0;} .form-horizontal .control-list{padding-top:0;} .form-horizontal .form-actions{padding-left:10px;padding-right:10px;} .modal{position:absolute;top:10px;left:10px;right:10px;width:auto;margin:0;}.modal.fade.in{top:auto;} .modal-header .close{padding:10px;margin:-10px;} .carousel-caption{position:static;}}@media (max-width:767px){body{padding-left:20px;padding-right:20px;} .navbar-fixed-top{margin-left:-20px;margin-right:-20px;} .container{width:auto;} .row-fluid{width:100%;} .row{margin-left:0;} .row>[class*="span"],.row-fluid>[class*="span"]{float:none;display:block;width:auto;margin:0;} .thumbnails [class*="span"]{width:auto;} input[class*="span"],select[class*="span"],textarea[class*="span"],.uneditable-input{display:block;width:100%;min-height:28px;-webkit-box-sizing:border-box;-moz-box-sizing:border-box;-ms-box-sizing:border-box;box-sizing:border-box;} .input-prepend input[class*="span"],.input-append input[class*="span"]{width:auto;}}@media (min-width:768px) and (max-width:979px){.row{margin-left:-20px;*zoom:1;}.row:before,.row:after{display:table;content:"";} .row:after{clear:both;} [class*="span"]{float:left;margin-left:20px;} .container,.navbar-fixed-top .container,.navbar-fixed-bottom .container{width:724px;} .span12{width:724px;} .span11{width:662px;} .span10{width:600px;} .span9{width:538px;} .span8{width:476px;} .span7{width:414px;} .span6{width:352px;} .span5{width:290px;} .span4{width:228px;} .span3{width:166px;} .span2{width:104px;} .span1{width:42px;} .offset12{margin-left:764px;} .offset11{margin-left:702px;} .offset10{margin-left:640px;} .offset9{margin-left:578px;} .offset8{margin-left:516px;} .offset7{margin-left:454px;} .offset6{margin-left:392px;} .offset5{margin-left:330px;} .offset4{margin-left:268px;} .offset3{margin-left:206px;} .offset2{margin-left:144px;} .offset1{margin-left:82px;} .row-fluid{width:100%;*zoom:1;}.row-fluid:before,.row-fluid:after{display:table;content:"";} .row-fluid:after{clear:both;} .row-fluid>[class*="span"]{float:left;margin-left:2.762430939%;} .row-fluid>[class*="span"]:first-child{margin-left:0;} .row-fluid > .span12{width:99.999999993%;} .row-fluid > .span11{width:91.436464082%;} .row-fluid > .span10{width:82.87292817100001%;} .row-fluid > .span9{width:74.30939226%;} .row-fluid > .span8{width:65.74585634900001%;} .row-fluid > .span7{width:57.182320438000005%;} .row-fluid > .span6{width:48.618784527%;} .row-fluid > .span5{width:40.055248616%;} .row-fluid > .span4{width:31.491712705%;} .row-fluid > .span3{width:22.928176794%;} .row-fluid > .span2{width:14.364640883%;} .row-fluid > .span1{width:5.801104972%;} input,textarea,.uneditable-input{margin-left:0;} input.span12, textarea.span12, .uneditable-input.span12{width:714px;} input.span11, textarea.span11, .uneditable-input.span11{width:652px;} input.span10, textarea.span10, .uneditable-input.span10{width:590px;} input.span9, textarea.span9, .uneditable-input.span9{width:528px;} input.span8, textarea.span8, .uneditable-input.span8{width:466px;} input.span7, textarea.span7, .uneditable-input.span7{width:404px;} input.span6, textarea.span6, .uneditable-input.span6{width:342px;} input.span5, textarea.span5, .uneditable-input.span5{width:280px;} input.span4, textarea.span4, .uneditable-input.span4{width:218px;} input.span3, textarea.span3, .uneditable-input.span3{width:156px;} input.span2, textarea.span2, .uneditable-input.span2{width:94px;} input.span1, textarea.span1, .uneditable-input.span1{width:32px;}}@media (max-width:979px){body{padding-top:0;} .navbar-fixed-top{position:static;margin-bottom:18px;} .navbar-fixed-top .navbar-inner{padding:5px;} .navbar .container{width:auto;padding:0;} .navbar .brand{padding-left:10px;padding-right:10px;margin:0 0 0 -5px;} .navbar .nav-collapse{clear:left;} .navbar .nav{float:none;margin:0 0 9px;} .navbar .nav>li{float:none;} .navbar .nav>li>a{margin-bottom:2px;} .navbar .nav>.divider-vertical{display:none;} .navbar .nav .nav-header{color:#999999;text-shadow:none;} .navbar .nav>li>a,.navbar .dropdown-menu a{padding:6px 15px;font-weight:bold;color:#999999;-webkit-border-radius:3px;-moz-border-radius:3px;border-radius:3px;} .navbar .dropdown-menu li+li a{margin-bottom:2px;} .navbar .nav>li>a:hover,.navbar .dropdown-menu a:hover{background-color:#222222;} .navbar .dropdown-menu{position:static;top:auto;left:auto;float:none;display:block;max-width:none;margin:0 15px;padding:0;background-color:transparent;border:none;-webkit-border-radius:0;-moz-border-radius:0;border-radius:0;-webkit-box-shadow:none;-moz-box-shadow:none;box-shadow:none;} .navbar .dropdown-menu:before,.navbar .dropdown-menu:after{display:none;} .navbar .dropdown-menu .divider{display:none;} .navbar-form,.navbar-search{float:none;padding:9px 15px;margin:9px 0;border-top:1px solid #222222;border-bottom:1px solid #222222;-webkit-box-shadow:inset 0 1px 0 rgba(255, 255, 255, 0.1),0 1px 0 rgba(255, 255, 255, 0.1);-moz-box-shadow:inset 0 1px 0 rgba(255, 255, 255, 0.1),0 1px 0 rgba(255, 255, 255, 0.1);box-shadow:inset 0 1px 0 rgba(255, 255, 255, 0.1),0 1px 0 rgba(255, 255, 255, 0.1);} .navbar .nav.pull-right{float:none;margin-left:0;} .navbar-static .navbar-inner{padding-left:10px;padding-right:10px;} .btn-navbar{display:block;} .nav-collapse{overflow:hidden;height:0;}}@media (min-width:980px){.nav-collapse.collapse{height:auto !important;overflow:visible !important;}}@media (min-width:1200px){.row{margin-left:-30px;*zoom:1;}.row:before,.row:after{display:table;content:"";} .row:after{clear:both;} [class*="span"]{float:left;margin-left:30px;} .container,.navbar-fixed-top .container,.navbar-fixed-bottom .container{width:1170px;} .span12{width:1170px;} .span11{width:1070px;} .span10{width:970px;} .span9{width:870px;} .span8{width:770px;} .span7{width:670px;} .span6{width:570px;} .span5{width:470px;} .span4{width:370px;} .span3{width:270px;} .span2{width:170px;} .span1{width:70px;} .offset12{margin-left:1230px;} .offset11{margin-left:1130px;} .offset10{margin-left:1030px;} .offset9{margin-left:930px;} .offset8{margin-left:830px;} .offset7{margin-left:730px;} .offset6{margin-left:630px;} .offset5{margin-left:530px;} .offset4{margin-left:430px;} .offset3{margin-left:330px;} .offset2{margin-left:230px;} .offset1{margin-left:130px;} .row-fluid{width:100%;*zoom:1;}.row-fluid:before,.row-fluid:after{display:table;content:"";} .row-fluid:after{clear:both;} .row-fluid>[class*="span"]{float:left;margin-left:2.564102564%;} .row-fluid>[class*="span"]:first-child{margin-left:0;} .row-fluid > .span12{width:100%;} .row-fluid > .span11{width:91.45299145300001%;} .row-fluid > .span10{width:82.905982906%;} .row-fluid > .span9{width:74.358974359%;} .row-fluid > .span8{width:65.81196581200001%;} .row-fluid > .span7{width:57.264957265%;} .row-fluid > .span6{width:48.717948718%;} .row-fluid > .span5{width:40.170940171000005%;} .row-fluid > .span4{width:31.623931624%;} .row-fluid > .span3{width:23.076923077%;} .row-fluid > .span2{width:14.529914530000001%;} .row-fluid > .span1{width:5.982905983%;} input,textarea,.uneditable-input{margin-left:0;} input.span12, textarea.span12, .uneditable-input.span12{width:1160px;} input.span11, textarea.span11, .uneditable-input.span11{width:1060px;} input.span10, textarea.span10, .uneditable-input.span10{width:960px;} input.span9, textarea.span9, .uneditable-input.span9{width:860px;} input.span8, textarea.span8, .uneditable-input.span8{width:760px;} input.span7, textarea.span7, .uneditable-input.span7{width:660px;} input.span6, textarea.span6, .uneditable-input.span6{width:560px;} input.span5, textarea.span5, .uneditable-input.span5{width:460px;} input.span4, textarea.span4, .uneditable-input.span4{width:360px;} input.span3, textarea.span3, .uneditable-input.span3{width:260px;} input.span2, textarea.span2, .uneditable-input.span2{width:160px;} input.span1, textarea.span1, .uneditable-input.span1{width:60px;} .thumbnails{margin-left:-30px;} .thumbnails>li{margin-left:30px;}}

data/lib/restapi_doc/template/assets/css/bootstrap.less

@@ -0,0 +1,9 @@
+@bodyBackground: #FFFFFF;
+@navBar: #ccccc;
+body {
+  background: @bodyBackground !important;
+}
+
+.navbar-inner{
+	background: @navBar !important;
+}