rapi_doc 0.3.1 → 0.4.0

data/lib/rapi_doc/rapi_config.rb

@@ -0,0 +1,40 @@
+module RapiDoc
+  module RapiConfig
+
+    # following helper methods return the directory location if no file type is specified or return the file location
+    # for that directory if one is supplied
+    def template_dir(f = nil)
+      @template_dir ||= File.join(File.dirname(__FILE__), '../../templates')
+      form_file_name @template_dir, f
+    end
+     
+    def config_dir(f = nil)
+      @config_dir ||= File.join(::Rails.root.to_s, 'config/rapi_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
+
+    # WARNING! - temp_dir will return different location for different runs. Use with Caution!
+    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/rapi_doc/resource_doc.rb

@@ -0,0 +1,85 @@
+# encoding: utf-8
+require_relative 'method_doc'
+
+module RapiDoc
+  # custom exception class
+  class ParsingException < Exception;
+  end
+  # 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, :class_block, :function_blocks, :resource_header, :resource_methods
+
+    # Initializes ResourceDoc.
+    def initialize(name, resource_location, controller_location, options = {})
+      @name = name
+      @class_block = nil
+      @function_blocks = []
+      @resource_methods = []
+      @resource_header = ""
+      @standard_methods = options[:standard_methods] || [:put, :post, :get, :delete]
+      @resource_location = resource_location
+      @controller_location = controller_location
+      @controller_name = File.basename(controller_location)
+    end
+
+    # parse the controller
+    def parse_apidoc!(class_template, method_template)
+      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
+      else
+        @resource_header = Haml::Engine.new(class_template).render(@class_block) unless class_block.nil?
+        @resource_methods = @function_blocks.each_with_index.collect do |method_block, i|
+          Haml::Engine.new(method_template).render(method_block)
+        end
+      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"
+            else
+              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 /class/ # keep track of whether a resource or an api is being annotated
+            in_class = true
+          else
+            if current_api_block # process ines 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/rapi_doc/tasks/rapi_doc_tasks.rake

@@ -1,41 +1,40 @@
-include RapiDoc::RapiConfig
+include RapiDoc::RAPIDoc
 
 namespace :rapi_doc do
+
   desc "Generate the config files"
   task :setup do
-    if File.directory?(config_dir)
-      puts "#{BASE_DIR}/#{File.basename(config_dir)} exists"
-    else
-      FileUtils.mkdir(config_dir)
-    end
-    %w(config_file layout_file class_layout_file frameset_file main_file).each do |type_file|
-      target_file = send(type_file, :target)
-      template_file = send(type_file, :template)
-      if File.exist? target_file
-        puts "#{BASE_DIR}/#{File.basename(target_file)} exists"
-      else
-        FileUtils.cp template_file, config_dir
-        puts "Generated #{BASE_DIR}/#{File.basename(template_file)}" # TODO Add instructions for users to update the config file
-      end
-    end
+    create_structure!
+    #puts "Now specify controllers in config/rapi_doc/config.yml for which api documentation is to be generated and then run rapi_doc::generate"
   end
-  desc "Generate the API Documentation"
+
+  desc "Generate the api documentation"
   task :generate do
-    begin
-      yml = YAML::load(File.open(config_file(:target)))
-    rescue
-      puts "It seems that you don't have the config files yet. Please run rake rapi_doc:setup"
+    resources = get_resources! do |controller, controller_url, controller_location|
+      print "Generate documentation for resource \"#{controller}\" mapped at \"#{controller_url}\" (\"#{File.basename(controller_location)}\")? (Y/n):"
+      response = STDIN.gets.chomp
+      ['y', 'Y'].include? response
     end
-
-    # Generating documentations
-    if yml
-      resources = []
-      yml.keys.each do |key|
-        resources << RapiDoc::ResourceDoc.new(key, yml[key]["location"], yml[key]["controller_name"])
-      end
-
+    if resources.empty?
+      puts "Nothing to generate"
+      #puts "Please specify controllers in config/rapi_doc/config.yml for which api documentation is to be generated and then run rapi_doc::generate again"
+    else
       # generate the apidoc
-      RapiDoc::RAPIDoc.new(resources)
+      puts "Generating API documentation..."
+      generate_templates!(resources)
+      move_structure!
+      puts "Finished."
     end
   end
+
+  desc "Clean up generated documentation"
+  task :clean do
+    remove_structure!
+  end
+
+  desc "Clean up everything - generated documentation and all the config"
+  task :distclean do
+    remove_all!
+  end
+
 end

data/templates/_resource_header.html.haml

@@ -0,0 +1,17 @@
+.resource_header
+  %h2= @name
+  %p.resource_summary= @content
+  - if @xml || @json
+    %h3 Representations
+    - if @json
+      .json
+        %p
+          %strong JSON representation:
+        %p
+          %textarea= @json
+    - if @xml
+      .xml
+        %p
+          %strong XML representation:
+        %p
+          %textarea= @xml

data/templates/_resource_method.html.haml

@@ -0,0 +1,38 @@
+.resource_methods
+  %a{:id => "#{@resource_name}_method_#{@method_order}"}
+  %p
+    %strong Description:
+    = @content
+  %h2= @url
+  - if @access
+    %strong Access:
+    = @access
+    %br/
+  - if @return
+    %strong Return:
+    = @return
+    %br/
+  - if @params
+    %strong Parameters:
+    %ul
+      - @params.each do |v|
+        %li= v
+  - unless @outputs.empty?
+    %ul.output_format
+      - @outputs.each do |output_format, output|
+        %li{:class => output_format}
+          %a{:href => "##{"#{@resource_name}_#{output_format}_#{@method_order}"}"}= output_format
+    .output
+      - @outputs.each do |output_format, output|
+        %div{:class => output_format}
+          %a{:id => "#{@resource_name}_#{output_format}_#{@method_order}"}
+          %pre.prettyprint= output
+    %br/
+  - unless @request.blank?
+    %strong Request:
+    %pre.code
+      %code= @request
+  - unless @response.blank?
+    %strong Response:
+    %pre.code
+      %code= @response

data/templates/index.html.haml

@@ -0,0 +1,40 @@
+!!!
+%html
+  %head
+    %meta{:content => "text/html; charset=utf-8", "http-equiv" => "Content-Type"}/
+    %link{:href => "styles.css", :rel => "stylesheet", :type => "text/css"}/
+    %script{:src => "http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.min.js", :type => "text/javascript"}
+    %script{:src => "scripts.js", :type => "text/javascript"}
+    %title apidoc
+  %body
+    #resource_index
+      %form{:onsubmit => "return false;"}
+        %input{:type => "text"}/
+        %img{:alt => "search", :src => "Search.png"}
+      %h2 Resources
+      %ul#resource_index
+        - resource_docs.each do |resource|
+          %li
+            %a{:href => "##{resource.name}"}= resource.name
+            - if resource.function_blocks.any?
+              %ul
+                - resource.function_blocks.each do |method_block|
+                  %li
+                    %a{:href => "##{resource.name}_method_#{method_block.method_order}"}
+                      = "#{method_block.method} #{method_block.url}"
+    #resources
+      %ul
+        %li
+          %strong Show XML
+          %a{:href => "#", :onclick => "$('.xml').toggle();"} toggle
+        %li
+          %strong Show JSON
+          %a{:href => "#", :onclick => "$('.json').toggle();"} toggle
+      - resource_docs.each do |resource|
+        %a{:id => "#{resource.name}"}
+        .resource
+          - if resource.resource_header
+            = resource.resource_header
+          - if resource.resource_methods
+            - resource.resource_methods.each do |method|
+              = method

data/templates/scripts.js

@@ -0,0 +1,22 @@
+/**
+ * created by: salilwadnerkar
+ * Date: 11/4/12
+ */
+$(function () {
+    $('#resource_index input').keyup(function(event) {
+        if ( event.keyCode == 13 ) {
+            event.preventDefault();
+        } else {
+            var search_txt = $(this).val();
+            var search_regex = new RegExp(search_txt, 'g');
+            $("#resource_index ul li").each ( function() {
+                var elem = $(this)
+                var h_elem = elem.find('a')[0];
+                var link_txt = h_elem.text;
+                var match = link_txt.match(search_regex);
+                match ? elem.show() : elem.hide();
+            });
+        }
+    });
+});
+

data/templates/styles.css

@@ -0,0 +1,80 @@
+html, body {
+    width: 100%;
+    height: 100%;
+}
+
+body {
+    line-height: 1.5em;
+}
+
+#resources {
+    float: right;
+    width: 80%;
+}
+
+#resource_index {
+    float: left;
+    height: 100%;
+    position: fixed;
+    width: 19%;
+    background-color: #ade;
+}
+
+#resource_index li {
+    background-color: #6699AA;
+    color:white;
+    padding: 5px 10px 0;
+}
+
+#resource_index li a {
+    display: block;
+    text-decoration: none;
+    font-weight: bold;
+    color:#ffffff;
+}
+
+#resource_index form img {
+    height: 25px;
+    width: 25px;
+}
+
+#resources h2 {
+    background-color: #6699AA;
+    color:white;
+}
+
+ul, ul li {
+    margin: 0;
+    padding: 0;
+    list-style: none outside;
+}
+
+h1, h2, h3 {
+    padding-top: 10px;
+    padding-bottom: 10px;
+}
+
+textarea {
+    width:100%;
+    height:200px;
+    display:none;
+}
+
+#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;
+}
+.code {
+    font-family: monospace;
+}

metadata

@@ -1,20 +1,21 @@
 --- !ruby/object:Gem::Specification
 name: rapi_doc
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
 - Husein Choroomi
 - Adinda Praditya
+- Salil Wadnerkar
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-17 00:00:00.000000000Z
+date: 2012-05-22 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70302725893440 !ruby/object:Gem::Requirement
+  requirement: &70219113103900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,43 +23,65 @@ dependencies:
         version: '2.1'
   type: :runtime
   prerelease: false
-  version_requirements: *70302725893440
+  version_requirements: *70219113103900
+- !ruby/object:Gem::Dependency
+  name: haml
+  requirement: &70219113100140 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70219113100140
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: &70219113098480 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70219113098480
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70302725892500 !ruby/object:Gem::Requirement
+  requirement: &70219113096980 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 2.7.0
   type: :development
   prerelease: false
-  version_requirements: *70302725892500
+  version_requirements: *70219113096980
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70302725891540 !ruby/object:Gem::Requirement
+  requirement: &70219113095540 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *70302725891540
+  version_requirements: *70219113095540
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70302725890700 !ruby/object:Gem::Requirement
+  requirement: &70219113094520 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 1.6.4
   type: :development
   prerelease: false
-  version_requirements: *70302725890700
+  version_requirements: *70219113094520
 - !ruby/object:Gem::Dependency
   name: rcov
-  requirement: &70302725889940 !ruby/object:Gem::Requirement
+  requirement: &70219113092920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -66,8 +89,31 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70302725889940
-description: Rails API Doc Generator
+  version_requirements: *70219113092920
+- !ruby/object:Gem::Dependency
+  name: haml
+  requirement: &70219113085900 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70219113085900
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: &70219113085080 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70219113085080
+description: Rails API Doc Generator. Parses the apidoc annotations to generate HTML
+  pages.
 email: hchoroomi@gmail.com
 executables: []
 extensions: []
@@ -75,6 +121,7 @@ extra_rdoc_files:
 - LICENSE.txt
 - README.md
 files:
+- .project
 - .rvmrc
 - Gemfile
 - Gemfile.lock
@@ -82,26 +129,25 @@ files:
 - README.md
 - Rakefile
 - VERSION
+- autoscan.log
+- configure.scan
 - init.rb
 - install.rb
-- lib/doc_parser.rb
-- lib/doc_util.rb
-- lib/method_doc.rb
-- lib/rapi_config.rb
 - lib/rapi_doc.rb
+- lib/rapi_doc/method_doc.rb
 - lib/rapi_doc/railtie.rb
+- lib/rapi_doc/rapi_config.rb
+- lib/rapi_doc/resource_doc.rb
 - lib/rapi_doc/tasks/rapi_doc_tasks.rake
-- lib/resource_doc.rb
 - spec/doc_parser_spec.rb
 - spec/method_doc_spec.rb
 - spec/spec_helper.rb
-- templates/_resource_header.html.erb
-- templates/_resource_method.html.erb
-- templates/class_layout.html.erb
-- templates/config.yml
-- templates/frameset.html.erb
-- templates/layout.html.erb
-- templates/main.html.erb
+- templates/Search.png
+- templates/_resource_header.html.haml
+- templates/_resource_method.html.haml
+- templates/index.html.haml
+- templates/scripts.js
+- templates/styles.css
 - uninstall.rb
 homepage: http://github.com/elc/rapi_doc
 licenses:
@@ -118,7 +164,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4532277263417640116
+      hash: 3223693436194821202
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: