rapi_doc 0.1.0

data/.rvmrc

@@ -0,0 +1 @@
+rvm ruby-1.9.2-p180@rapidoc --create

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.6.4"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,20 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.6.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.9.2.2)
+    rcov (0.9.11)
+    shoulda (2.11.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.6.4)
+  rcov
+  shoulda

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Husein Choroomi
+
+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

@@ -0,0 +1,44 @@
+@WIP
+Based on RAPI Doc by Jaap van der Meer found here: http://code.google.com/p/rapidoc/
+
+Rails API Doc Generator
+Original Author: JPM van der Meer
+Modified By: Chelsea Robb
+=======================
+With API DOC one can generate code for a Restful Rails API.
+It generates a set of HTML views in the public directory.  Parses the desired controllers and generates appropriate views.
+Currently does not read routes.rb and requires manual entry of routes
+
+=INSTALL
+    gem install rapi_doc
+
+==Layout files
+You can find documentation layouts in config/rapi_doc
+
+index.html.erb is used for index page.
+resource.html.erb is used for individual controllers.
+
+==Usage
+Run 'rake rapi_doc' to generate config and layout files. (TODO: Add a separte rake task to generate config files)
+Modify config file by adding your controllers, e.g.:
+
+users:
+  location: "/users"
+  controller_name: "users_controller.rb"
+
+Then invoke the generation by calling:
+    rake rapi_doc
+
+==Documentation Example
+
+=begin apidoc
+url:: /users
+method:: GET
+access:: FREE
+return:: [JSON|XML] - list of user objects
+param:: page:int - the page, default is 1
+param:: per_page:int - max items per page, default is 10
+
+Get a list of all users in the system with pagination.  Defaults to 10 per page
+=end
+

data/Rakefile

@@ -0,0 +1,53 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "rapi_doc"
+  gem.homepage = "http://github.com/hchoroomi/rapi_doc"
+  gem.license = "MIT"
+  gem.summary = %Q{Rails API Doc Generator}
+  gem.description = %Q{Rails API Doc Generator}
+  gem.email = "hchoroomi@gmail.com"
+  gem.authors = ["Husein Choroomi"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+  test.rcov_opts << '--exclude "gems/*"'
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rapi_doc #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/init.rb

@@ -0,0 +1 @@
+require 'rapi_doc'

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/config.rb

@@ -0,0 +1,25 @@
+module Config
+  def config_dir
+    File.join(::Rails.root.to_s, 'config/rapi_doc')
+  end
+
+  def template_dir
+    File.join(File.dirname(__FILE__), '/../templates')
+  end
+
+  def config_file(location)
+    File.join(find_location(location), 'config.yml')
+  end
+
+  def index_layout_file(location)
+    File.join(find_location(location), 'index.html.erb')
+  end
+
+  def resource_layout_file(location)
+    File.join(find_location(location), 'resource.html.erb')
+  end
+
+  def find_location(location)
+    location == :target ? config_dir : template_dir
+  end
+end

data/lib/doc_util.rb

@@ -0,0 +1,6 @@
+class DocUtil
+  # print some  erb code to a template
+  def self.print_erb(str, show=false)
+    (show ? "<%= " : "<% ") + str + " %>"
+  end
+end

data/lib/method_doc.rb

@@ -0,0 +1,32 @@
+# This class holds methods about a doc.
+class MethodDoc
+  attr_accessor :scope, :content, :request, :response, :code
+  
+  def initialize(type)
+    @scope = type
+    @variables = []
+    @content = ""
+    @code = ""
+    @request = ""
+    @response = ""
+  end
+  
+  
+  def add_variable(name, value)
+    if name == "param"
+      @variables << value
+      return
+    end
+
+    eval("@#{name}= \"#{value}\"")
+
+    if name == "json"
+      puts "Found json:"
+      puts @json
+    end
+  end
+  
+  def get_binding
+    binding
+  end
+end

data/lib/rapi_doc/railtie.rb

@@ -0,0 +1,9 @@
+require 'rails'
+
+module RapiDoc
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load 'rapi_doc/tasks/rapi_doc_tasks.rake'
+    end
+  end
+end

data/lib/rapi_doc/tasks/rapi_doc_tasks.rake

@@ -0,0 +1,24 @@
+desc "Generate the API Documentation"
+task :rapi_doc do
+  begin
+    yml = YAML::load(File.open(config_file(:target)))
+  rescue
+    FileUtils.mkdir(config_dir) if (!File.directory?(config_dir))
+    [config_file(:template), index_layout_file(:template), resource_layout_file(:template)].each do |_file|
+      FileUtils.cp _file, config_dir
+      puts "Generated config/rapi_doc/#{File.basename(_file)}" # TODO Add instructions for users to update the config file
+    end
+  end
+
+  # Generating documentations
+  if yml
+    resources = []
+    yml.keys.each do |key|
+      resources << ResourceDoc.new(key, yml[key]["location"], yml[key]["controller_name"])
+    end
+
+    # generate the apidoc
+    RAPIDoc.new(resources)
+  end
+end
+

data/lib/rapi_doc.rb

@@ -0,0 +1,69 @@
+require 'erb'
+require 'fileutils'
+require 'doc_util'
+require 'resource_doc'
+require 'config'
+require 'rapi_doc/railtie' if defined?(Rails)
+
+include Config # TODO FIXME
+
+class RAPIDoc
+
+  # Initalize the ApiDocGenerator
+  def initialize(resources)
+    puts "Apidoc started..."
+    @resources = resources
+    generate_templates!
+    move_structure!
+    puts "Finished."
+  end
+
+  # Iterates over the resources creates views for them.
+  # Creates an index file
+  def generate_templates!
+
+    @resources.each do |r|
+      r.parse_apidoc!
+      r.generate_view!(@resources, temp_dir)
+    end
+    generate_index!
+    copy_styles!
+  end
+
+  # generate the index file for the api views
+  def generate_index!
+    template = ""
+    File.open(index_layout_file(:target)).each { |line| template << line }
+    parsed = ERB.new(template).result(binding)
+    File.open(File.join(temp_dir, "index.html"), 'w') { |file| file.write parsed }
+  end
+
+  def move_structure!
+    target_folder = "#{::Rails.root.to_s}/public/apidoc/"
+    Dir.mkdir(target_folder) if (!File.directory?(target_folder))
+
+    Dir.new(temp_dir).each do |d|
+      if d =~ /^[a-zA-Z]+\.(html|css)$/ # Only want to copy over the .html files, not the .erb templates
+        FileUtils.cp  File.join(temp_dir + d), target_folder + d
+      end
+
+      #Clean up the no longer needed files
+      filepath = "#{temp_dir}/#{d}"
+      File.delete(filepath) unless File.directory?(filepath)
+    end
+  end
+
+  def copy_styles!
+    Dir[File.join(File.dirname(__FILE__), '..', 'templates/*')].each do |f|
+      if f =~ /[\/a-zA-Z\.]+\.css$/i
+        FileUtils.cp f, temp_dir
+      end
+    end
+  end
+
+  private
+
+  def temp_dir
+    @temp_dir ||= "#{Dir.mktmpdir("apidoc")}/"
+  end
+end

data/lib/resource_doc.rb

@@ -0,0 +1,124 @@
+require 'method_doc'
+
+# ResourceDoc holds the information a resource contains. It parses the class header and also the 
+# method documentation, which will be contained in MethodDoc.
+class ResourceDoc
+  
+  attr_reader :name, :resource_location, :controller_name, :function_blocks, :class_block
+  
+  # Initializes RAPIDoc.
+  def initialize(name, resource_location, controller_name, options = {})
+    @name = name
+    @standard_methods = options[:standard_methods] || [:put, :post, :get, :delete]
+    @resource_location, @controller_name = resource_location, controller_name
+    @function_blocks = []
+    @method_codes = []
+    @header_code = ""
+    
+    unless File.exist?(controller_location)
+      raise "Unable to find or open controller. Make sure it's set properly in config/rapidoc/config.yml File: #{controller_location}"
+    end
+  end
+  
+  # returns the location of the controller that is to be parsed
+  def controller_location
+    "#{::Rails.root.to_s}/app/controllers/#{controller_name}"
+  end
+  
+  def get_binding
+    binding
+  end
+  
+  # parse the controller
+  def parse_apidoc!
+    current_api_block = nil
+    current_scope = :none
+    block_holder = []
+    lineno = 0
+    inclass = false
+    
+    File.open(controller_location).each do |line|
+      if line =~ /=begin apidoc/
+        current_scope = !inclass ? :class : :function
+        current_api_block = MethodDoc.new(current_scope)
+      elsif line =~ /=end/
+        if current_api_block.nil?
+          puts "#{controller_location}:#{lineno} - No starttag for =end found"
+          exit
+        elsif current_api_block.scope == :class
+          @class_block = current_api_block
+        elsif current_api_block.scope == :function
+          @function_blocks << current_api_block
+        end
+        current_api_block = nil
+        current_scope = :none
+      elsif line =~ /class/
+        inclass = true
+      elsif line =~ /::response-end::/
+        current_scope = :function
+      elsif line =~ /::request-end::/
+        current_scope = :function
+      elsif current_scope == :response
+        current_api_block.response += "#{line}"
+      elsif current_scope == :request
+        current_api_block.request += "#{line}"
+      elsif current_scope == :class || current_scope == :function # check if we are looking at a api block
+        # strip the # on the line
+        #line = line[1..line.length].lstrip.rstrip
+        # check if we are dealing with a variable
+        # something in the format: # varname:: sometext
+        if result = /(\w+)\:\:\s*(.+)/.match(line)
+          if result[1] == "response" || result[1] == "request"
+            puts "="*30
+            puts "found response"
+            puts "="*30; puts ""
+            puts line
+            current_scope = result[1].to_sym
+          else
+            current_api_block.add_variable(result[1], result[2])
+          end
+        else
+          # add line to block
+          current_api_block.content << line
+        end
+      end
+      lineno += 1
+    end
+
+    puts "Generated #{name}.html"
+  end
+  
+  def generate_view!(resources, temp_dir)
+     @resources = resources
+     @header_code = get_parsed_header unless @class_block.nil?
+     function_blocks.each do |mb|
+       @method_codes << get_parsed_method(mb)
+     end
+     # write it to a file
+     template = ""
+     File.open(resource_layout_file(:target)).each { |line| template << line }
+     parsed = ERB.new(template).result(binding)
+     File.open(File.join(temp_dir, name + ".html"), 'w') { |file| file.write parsed }
+  end
+
+
+  def get_parsed_header
+    template = ""
+    File.open(File.join(File.dirname(__FILE__), '..', 'templates', '_resource_header.html.erb')).each { |line| template << line }
+
+    puts "-"*30
+    puts ">>> inside: get_parsed_header"
+    puts ERB.new(template).result(@class_block.get_binding)
+    puts "-"*30; puts ""
+
+    return ERB.new(template).result(@class_block.get_binding)
+  end
+
+
+  def get_parsed_method(method_block)
+    template = ""
+    File.open(File.join(File.dirname(__FILE__), '..', 'templates', '_resource_method.html.erb')).each { |line| template << line }
+    return ERB.new(template).result(method_block.get_binding)
+  end
+    
+end

data/templates/_resource_header.html.erb

@@ -0,0 +1,18 @@
+<h1><%=@name %></h1>
+<p class="summary"><%=@content %></p>
+
+<% if @xml || @json %>
+  <h2>Representations</h2>
+
+  <% if @json %>
+    <a name="json"></a>
+    <strong>JSON representation:</strong> <br /><a href="javascript:$('#jsonrep').toggle()">(toggle code)</a><br />
+    <textarea style="width:100%;height:200px;display:none;" id="jsonrep"><%=@json %></textarea><br />
+  <% end %>
+
+  <% if @xml %>
+    <a name="xml"></a>
+    <strong>XML representation:</strong> <br /><a href="javascript:$('#xmlrep').toggle()">(toggle code)</a><br/>
+    <textarea style="width:100%;height:200px;display:none;" id="xmlrep"><%=@xml %></textarea>
+  <% end %>
+<% end %>

data/templates/_resource_method.html.erb

@@ -0,0 +1,39 @@
+<div id="method">
+  
+  <%
+    splitted = @method
+    str = @method
+    str = "<span id='http_verb'>#{str}</span>"
+  %>
+  <p class='description'><strong>Description:</strong> <%=@content %></p>
+
+  <h2><%=str %><%=@url %></h2>
+  
+  <% if @access %>
+    <strong>Access:</strong> <%=@access %><br />
+  <% end %>
+
+  <% if @return %>
+    <strong>Return:</strong>
+    <%=@return %>
+    <br />
+  <% end %>
+
+  <% if @variables %>  
+    <strong>Parameters:</strong>
+    <ul>
+      <% @variables.each do |v| %><li><%=v %></li><% end %>
+    </ul>
+  <% end %>
+
+  <% unless @request.blank? %>
+    <strong>Request:</strong>
+    <pre class="code"><code><%= @request %></code></pre>
+  <% end %>
+
+  <% unless @response.blank? %>  
+    <strong>Response:</strong>
+    <pre class="code"><code><%= @response %></code></pre>
+  <% end %>
+
+</div>

data/templates/config.yml

@@ -0,0 +1,3 @@
+#users:
+#  location: "/users"
+#  controller_name: "users_controller.rb"

data/templates/index.html.erb

@@ -0,0 +1,67 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title><%= @name || 'Home' %></title>
+
+    <style>
+      body {
+        line-height: 1.5em;
+        color:#484848;
+      }
+
+      ul, ol {
+        margin-bottom: 0.8em;
+      }
+
+      li {
+        padding-left: 10px;
+        margin-right: 10px;
+      }
+
+      #resources {
+
+      }
+
+      h1, h2, h3 {
+        padding-top: 8px;
+        padding-bottom: 2px;
+      }
+
+      #method {
+        padding: 15px 30px;
+        border-top:1px solid #ddd;
+      }
+
+      #http_verb {
+        color:#ff6600;
+        width:200px;
+        margin-right:20px;'
+      }
+
+      .description{
+        font-size: 1.4em;
+        color:#262626;
+      }
+    </style>
+
+  </head>
+  <body>
+    <div class="content">
+
+      <div id="introduction">
+        <!-- documentation intro -->
+      </div>
+
+      <h2>Resources</h2>
+      <div id="resources">
+        <ul>
+        <% @resources.each do |r| %>
+          <li>Resource:  <a href="/apidoc/<%=r.name %>.html"><%=r.resource_location %></a></li>
+        <% end %>
+        </ul>
+      </div>
+
+    </div>
+  </body>
+</html>

data/templates/resource.html.erb

@@ -0,0 +1,67 @@
+<!-- TODO Use same layout for index and resources -->
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title><%= @name || 'Home' %></title>
+
+    <style>
+      body {
+        line-height: 1.5em;
+        color:#484848;
+      }
+
+      ul, ol {
+        margin-bottom: 0.8em;
+      }
+
+      li {
+        padding-left: 10px;
+        margin-right: 10px;
+      }
+
+      #resources {
+
+      }
+
+      h1, h2, h3 {
+        padding-top: 8px;
+        padding-bottom: 2px;
+      }
+
+      #method {
+        padding: 15px 30px;
+        border-top:1px solid #ddd;
+      }
+
+      #http_verb {
+        color:#ff6600;
+        width:200px;
+        margin-right:20px;'
+      }
+
+      .description{
+        font-size: 1.4em;
+        color:#262626;
+      }
+    </style>
+
+  </head>
+  <body>
+    <div class="content">
+      <div id="navigation"> 
+        <ul class="main">
+          <li><a href="/apidoc/index.html">&laquo; Back to index</a></li>
+        </ul>
+      </div>
+
+      <hr />
+
+      <%=@header_code %>
+
+      <% @method_codes.each do |mc| %>
+        <%=mc %>
+      <% end %>
+    </div>
+  </body>
+</html>

data/test/rapi_doc_test.rb

@@ -0,0 +1,8 @@
+require 'test_helper'
+
+class RapiDocTest < ActiveSupport::TestCase
+  # Replace this with your real tests.
+  test "the truth" do
+    assert true
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'active_support'
+require 'active_support/test_case'

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification 
+name: rapi_doc
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Husein Choroomi
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-10-31 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.6.4
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id004
+description: Rails API Doc Generator
+email: hchoroomi@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README
+files: 
+- .rvmrc
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README
+- Rakefile
+- VERSION
+- init.rb
+- install.rb
+- lib/config.rb
+- lib/doc_util.rb
+- lib/method_doc.rb
+- lib/rapi_doc.rb
+- lib/rapi_doc/railtie.rb
+- lib/rapi_doc/tasks/rapi_doc_tasks.rake
+- lib/resource_doc.rb
+- templates/_resource_header.html.erb
+- templates/_resource_method.html.erb
+- templates/config.yml
+- templates/index.html.erb
+- templates/resource.html.erb
+- test/rapi_doc_test.rb
+- test/test_helper.rb
+- uninstall.rb
+homepage: http://github.com/hchoroomi/rapi_doc
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 2005719792368905649
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: Rails API Doc Generator
+test_files: []
+