rapi_doc 0.3.1 → 0.4.0

data/.project

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>rapi_doc</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>com.aptana.ide.core.unifiedBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>com.aptana.ruby.core.rubynature</nature>
+	</natures>
+</projectDescription>

data/.rvmrc

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

data/Gemfile

@@ -4,12 +4,14 @@ source "http://rubygems.org"
 #   gem "activesupport", ">= 2.3.5"
 
 gem 'activesupport', '>= 2.1'
+gem 'haml'
+gem 'rdoc'
 
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do
-  gem "rspec", "~> 2.7.0"
-  gem "bundler", "~> 1.0.0"
-  gem "jeweler", "~> 1.6.4"
+  gem "rspec", ">= 2.7.0"
+  gem "bundler", ">= 1.0.0"
+  gem "jeweler", ">= 1.6.4"
   gem "rcov", ">= 0"
 end

data/Gemfile.lock

@@ -5,13 +5,17 @@ GEM
       multi_json (~> 1.0)
     diff-lcs (1.1.3)
     git (1.2.5)
+    haml (3.1.4)
     jeweler (1.6.4)
       bundler (~> 1.0)
       git (>= 1.2.5)
       rake
+    json (1.6.6)
     multi_json (1.0.4)
     rake (0.9.2.2)
     rcov (0.9.11)
+    rdoc (3.12)
+      json (~> 1.4)
     rspec (2.7.0)
       rspec-core (~> 2.7.0)
       rspec-expectations (~> 2.7.0)
@@ -26,7 +30,9 @@ PLATFORMS
 
 DEPENDENCIES
   activesupport (>= 2.1)
-  bundler (~> 1.0.0)
-  jeweler (~> 1.6.4)
+  bundler (>= 1.0.0)
+  haml
+  jeweler (>= 1.6.4)
   rcov
-  rspec (~> 2.7.0)
+  rdoc
+  rspec (>= 2.7.0)

data/README.md

@@ -13,19 +13,78 @@ Installation
 Usage
 =====
 
-Run `rake rapi_doc:setup` to generate config and layout files.
-
-Modify config file by adding your controllers, e.g.:
-
-    books:
-      location: "/books"
-      controller_name: "books_controller.rb"
+Run `rake rapi_doc:setup` to generate default Haml template files along with default styles.
+These files are in `<application folder>/config/rapi_doc` folder. 
 
 Then invoke the generation by calling:
 
 `rake rapi_doc:generate`
 
-Documentation Example
+It will analyze `rake routes` output and find the controller files in app/controllers directory that may have the annotation.
+It will confirm from the user whether he/she wants the plugin to look for annotations in each of these files.
+For files confirmed by the user, it will parse the annotations and generate the HTML output using the template files and styles
+in the `config/rapi_doc` folder.
+
+`rake rapi_doc:clean`
+will remove the documentation thus generated.
+
+`rake rapi_doc:distclean`
+will remove the documentation and also the Haml template files and styles created by the `rake rapi_doc:setup`
+
+
+Markup Reference
+================
+
+Controller methods and controllers themselves are documented by annotating them with "method markers" and
+"resource markers" enclosed in "apidoc" comments, similar to that in RDoc.
+
+  # =begin apidoc
+  ... method markers
+  # =end
+
+A] Method markers
+-----------------
+
+Method markers are specified like this:
+
+    # <<method-marker-name>:: <method-marker-value>
+
+All method markers are optional.
+
+    # method: HTTP request type such as GET or POST
+    # access: access restrictions such as FREE, RESTRICTED for paid subscribers, etc
+    # return: list of return data-formats like [JSON|XML] and what the return data means
+    # param: name and type of the parameter expected
+    # output: output format like JSON, XML. It is recommended that it should include an example of such data.
+    #         Each output marker must end with ::output-end:: on a separate line.
+    # request: a request generating code example
+    # response: a response processing code example
+
+You can define your own custom method markers as well.
+They will be available as the instance variables against which the _resource_method.html.erb template
+will be evaluated.
+
+Any other information that needs to be shown in the view can be specified in the apidoc comments as well.
+It will be shown under the "Description" section for the method in the view.
+
+
+B] Resource markers
+-------------------
+
+A resource, which is normally a controller object, can also be annotated with apidoc comments. 
+
+Method markers are specified the same way as the method markers:
+
+    # <<method-marker-name>:: <method-marker-value>
+    # 
+    # xml: xml representation of the resource
+    # json: json representation
+
+Just like in method marker, any other information that needs to be shown in the view can be specified in the apidoc comments as well.
+It will be shown under the "Description" section for the method in the view.
+
+
+C] Documentation Example
 ---------------------
 
     # =begin apidoc
@@ -63,14 +122,66 @@ Documentation Example
     # Get a list of all books in the system with pagination.  Defaults to 10 per page
     # =end
 
-    
-Layout
-------
 
-Documentation layout is located at `config/rapi_doc/layout.html.erb`.
+
+Haml Templates and styles
+=========================
+
+Resource and resource method annotations are available as instance and local variables in Haml templates.
+Here are the listing of variables available. But the best way to understand it is to look at the default 
+Haml templates generated by `rake rapi_doc:setup` in `config/rapi_doc` folder.
+
+
+A] Resource Method
+------------------
+
+    @resource_name: Resource name
+    @method_order: the numerical order of the method
+    @content: All Misc info
+    @url: url
+    @access: public/privileged, etc
+    @return: the data format of the info
+    @params: params expected by this api
+    @outputs: array of [output_format, output example], for example, [json, ....json output.. ]
+    @request: example of the data expected
+    @response: example of the response
+
+
+B] Resource
+-----------
+
+    @name: name
+    @xml: xml representation of the resource
+    @json: json representation
+    @function_blocks: Array of resource method objects described above
+
+
+    Following instance variables are only available in the index template described below (and not in the resource Haml template)
+    @resource_methods: Array of HTML generated for each of the methods. 
+    @resource_header: HTML generated for the resource
+
+
+C] Index
+--------
+
+    resource_docs: all the resource objects, whose instance variables are described above.
+    As mentioned before, for each resource, the HTML generated for the resource itself is available in @resource_header
+    and HTML generated for each of its methods is available in @resource_methods array. 
+
+
+
+D] Documentaton Output
+----------------------
+
+Documentation generated is located in `public/apidoc` directory.
+
+    index.html: contains the HTML 
+    styles.css: CSS styles
+    scripts.js: contains the script used to search within the documentation.
+
 
 Credit
 ======
 
 * Based on RAPI Doc by Jaap van der Meer found here: http://code.google.com/p/rapidoc/
-* https://github.com/sabman/rapi_doc
+* https://github.com/sabman/rapi_doc

data/Rakefile

@@ -18,10 +18,12 @@ Jeweler::Tasks.new do |gem|
   gem.homepage = "http://github.com/elc/rapi_doc"
   gem.license = "MIT"
   gem.summary = %Q{Rails API Doc Generator}
-  gem.description = %Q{Rails API Doc Generator}
+  gem.description = %Q{Rails API Doc Generator. Parses the apidoc annotations to generate HTML pages.}
   gem.email = "hchoroomi@gmail.com"
-  gem.authors = ["Husein Choroomi", "Adinda Praditya"]
+  gem.authors = ["Husein Choroomi", "Adinda Praditya", "Salil Wadnerkar"]
   # dependencies defined in Gemfile
+  gem.add_dependency 'haml'
+  gem.add_dependency 'rdoc'
 end
 Jeweler::RubygemsDotOrgTasks.new
 
@@ -42,8 +44,8 @@ end
 
 task :default => :test
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
+require 'rdoc/task'
+RDoc::Task.new do |rdoc|
   version = File.exist?('VERSION') ? File.read('VERSION') : ""
 
   rdoc.rdoc_dir = 'rdoc'

data/VERSION

@@ -1 +1 @@
-0.3.1
+0.4.0

data/configure.scan

@@ -0,0 +1,17 @@
+#                                               -*- Autoconf -*-
+# Process this file with autoconf to produce a configure script.
+
+AC_PREREQ(2.61)
+AC_INIT(FULL-PACKAGE-NAME, VERSION, BUG-REPORT-ADDRESS)
+
+# Checks for programs.
+
+# Checks for libraries.
+
+# Checks for header files.
+
+# Checks for typedefs, structures, and compiler characteristics.
+
+# Checks for library functions.
+
+AC_OUTPUT

data/lib/rapi_doc.rb

@@ -1,76 +1,100 @@
-require 'erb'
+require 'haml'
 require 'fileutils'
-require 'doc_util'
-require 'resource_doc'
-require 'rapi_config'
-require 'rapi_doc/railtie' if defined?(Rails)
+require_relative 'rapi_doc/resource_doc'
+require_relative 'rapi_doc/rapi_config'
+require_relative 'rapi_doc/railtie' if defined?(Rails)
 
 module RapiDoc
-  class RAPIDoc
+ module RAPIDoc
 
     include RapiConfig
+    include FileUtils::Verbose # so that each mv/cp/mkdir gets printed and user is aware of what is happening
 
-    # Initalize the ApiDocGenerator
-    def initialize(resources)
-      puts "Apidoc started..."
-      @resources = resources
-      generate_templates!
-      move_structure!
-      puts "Finished."
+    def create_structure!
+      File.directory?(config_dir) || mkdir(config_dir)
+      Dir["#{template_dir}/*.*"].each do |template_file|
+        target_file = config_dir(File.basename(template_file))
+        cp template_file, config_dir if not File.exist? target_file
+      end
     end
 
-    # Iterates over the resources creates views for them.
-    # Creates an index file
-    def generate_templates!
+    # Reads 'rake routes' output and gets the controller info
+    def get_controller_info!
+      controller_info = {}
+      routes = Dir.chdir(::Rails.root.to_s) { `rake routes` }
+      routes.split("\n").each do |entry|
+        method, url, controller_action = entry.split.slice(-3, 3)
+        controller, action = controller_action.split('#')
+        puts "For \"#{controller}\", found action \"#{action}\" with #{method} at \"#{url}\""
+        controller_info[controller] ||= []
+        controller_info[controller] << [action, method, url]
+      end
+      controller_info
+    end
 
-      @resources.each do |r|
-        r.parse_apidoc!
-        r.generate_view!(@resources, temp_dir)
+    def get_resources!
+      #yml = get_config || []
+      #yml.collect { |key, val| ResourceDoc.new(key, val["location"], controller_dir(val["controller_name"])) }
+      controller_info = get_controller_info!
+      resources = []
+      controller_info.each do |controller, action_entries|
+        #controller_class = controller.capitalize + 'Controller'
+        controller_location = controller_dir(controller + '_controller.rb')
+        controller_base_routes = action_entries.select do |action, method, url|
+          url.index('/', 1).nil?
+        end
+        # base urls differ only by the method [GET or POST]. So, any one will do.
+        controller_url = controller_base_routes[0][2].gsub(/\(.*\)/, '') # omit the trailing format
+        #controller_methods = controller_base_routes.map { |action, method, url| method }
+        if block_given?
+          controller_include = yield [controller, controller_url, controller_location]
+        else
+          controller_include = true
+        end
+        resources << ResourceDoc.new(controller, controller_url, controller_location) if controller_include
       end
-      generate_index!
-      copy_styles!
+      resources
     end
 
-    # generate the index file for the api views
-    def generate_index!
-      template = ""
-      @page_type2 = 'dudul'
-      File.open(class_layout_file(:target)).each { |line| template << line }
-      parsed = ERB.new(template).result(binding)
-      File.open(File.join(temp_dir, "class.html"), 'w') { |file| file.write parsed }
+    # Generates views and their index in a temp directory
+    def generate_templates!(resource_docs)
+      generate_resource_templates!(resource_docs)
+      copy_styles!
     end
 
+    # Moves the generated files in the temp directory to target directory
     def move_structure!
-      target_folder = "#{::Rails.root.to_s}/public/apidoc/"
-      Dir.mkdir(target_folder) if (!File.directory?(target_folder))
+      Dir.mkdir(target_dir) if (!File.directory?(target_dir))
+      # Only want to move the .html, .css, .png and .js files, not the .haml templates.
+      html_css_files = temp_dir("*.{html,css,js,png}")
+      Dir[html_css_files].each { |f| mv f, target_dir }
+    end
 
-      # Copy the frameset & main files
-      FileUtils.cp frameset_file(:target), target_folder + 'index.html'
-      FileUtils.cp main_file(:target), target_folder + 'main.html'
+    # Removes the generated files
+    def remove_structure!
+      rm_rf target_dir
+    end
 
-      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
+    # Remove all files - config and generated
+    def remove_all!
+      remove_structure!
+      rm_rf config_dir
+    end
 
-        #Clean up the no longer needed files
-        filepath = "#{temp_dir}/#{d}"
-        File.delete(filepath) unless File.directory?(filepath)
-      end
+    # Creates views for the resources
+    def generate_resource_templates!(resource_docs)
+      class_template = IO.read(template_dir('_resource_header.html.haml'))
+      method_template = IO.read(template_dir('_resource_method.html.haml'))
+      resource_docs.each { |resource| resource.parse_apidoc!(class_template, method_template) }
+      template = IO.read(config_dir('index.html.haml'))
+      parsed = Haml::Engine.new(template).render(Object.new, :resource_docs => resource_docs)
+      File.open(temp_dir("index.html"), 'w') { |file| file.write parsed }
     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
+      css_js_files = config_dir("*.{css,js,png}")
+      Dir[css_js_files].each { |f| cp f, temp_dir }
     end
 
-    private
-
-    def temp_dir
-      @temp_dir ||= "#{Dir.mktmpdir("apidoc")}/"
-    end
   end
 end

data/lib/rapi_doc/method_doc.rb

@@ -0,0 +1,71 @@
+module RapiDoc
+  # This class holds methods about a doc.
+  class MethodDoc
+    attr_accessor :scope, :method_order, :content, :request, :response, :outputs, :params
+    
+    def initialize(resource_name, type, order)
+      @resource_name = resource_name
+      @scope = type
+      @method_order = order
+      @content = ""
+      @request = ""
+      @response = ""
+      @outputs = {}
+      @params = []
+    end
+
+    def process_line(line, current_scope)
+      #puts "In scope #{current_scope} processing: #{line}"
+      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
+          last_output_key = @outputs.keys.last
+          @outputs[last_output_key] << ERB::Util.html_escape(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
+            @outputs[value] = '' # add the new output format as a key
+          when "param"
+            @params << 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