rapidoc 0.0.4

data/.gitignore

@@ -0,0 +1,21 @@
+*.swp
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.rvmrc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+spec/dummy/rapidoc
+spec/dummy/config/rapidoc

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ns-api-doc.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,20 @@
+MIT License
+
+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,152 @@
+= Rapidoc
+
+REST API documentation generator for rails projects ( 0.04 version ).
+
+This gem let you generate API documentation of your rails project in html format.
+It use routes information, _rapidoc_ _comments_ and json examples for generate
+static html files.
+
+This is how the web interface look like:
+
+* Resources: example[http://www.v2imagen.com/RDv]
+* Action-home: example[http://es.zimagez.com/zimage/capturadepantalla-170213-195254.php]
+
+Rapidoc is based in restapi_doc gem: https://github.com/Alayho/restapi_doc
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'rapidoc', :git => 'https://github.com/drinor/rapidoc.git'
+
+And then execute:
+
+    $ bundle
+
+== Usage
+
+For generate documentation run:
+
+    rake rapidoc:generate
+
+For clean all generate files run:
+
+    rake rapidoc:clean
+
+== Configuration
+
+You can configure rapidoc in ``/config/rapidoc/rapidoc.yml`` file:
+
+  project_name: "Project Name"
+  company: "My company"
+  year: 2013
+  doc_route: "doc"
+  examples_route: "examples"
+
+The first three parameters are used for show information about project.
+
+The *doc_route* parameter let you specify where _rapidoc_ will generate all the
+documentation:
+
+  path_project/name
+
+The *examples_route* parameter let you specify where _rapidoc_ will search for
+requests/responeses examples files:
+
+  path_project/name
+
+For more details please visit the Wiki[https://github.com/drinor/rapidoc/wiki].
+
+== Introducction
+
+If you generate documentation without do anithing, you can get all resources list in a _index.html_ file.
+
+For get resources documentation you need add a resource block to resource controller:
+
+  # =begin resource
+  # =end
+
+For get action documentation you need add an action block to resource controller:
+
+  # =begin action
+  # =end
+
+Documentation blocks use *yaml* format.
+
+== Requests/Responses examples
+
+Rapidoc let you define *json* files with requests/responses examples. You only need to add
+your files to *examples_route* and _rapidoc_ load it automatically in an action tab.
+
+Files should have the next name format:
+
+  <resource>_<action>_<type>.json
+
+Parameters:
+
+* *resource*: name of resource (plural)
+* *action*: controller action (index, create, show...)
+* *type*: request / response
+
+Name example:
+
+  users_create_request.json
+
+File example:
+
+  {
+    "usuario": {
+      "name": "Paul",
+      "age": 23,
+      "height": 1.7,
+      "favoriteBands": ["Band ABC", "Band XYZ"]
+    }
+  }
+
+== Documentation examples
+
+Resource documentation:
+
+  # users_controller.rb
+
+  # =begin resource
+  # description: Represents an user in the system.
+  # =end
+
+Action documentation:
+
+  # =begin action
+  # method: GET
+  # action: index
+  # requires_authentication: no
+  # response_formats: json
+  # description: Return all users of the system.
+  #
+  # http_responses:
+  #   - 200
+  #   - 401
+  #   - 403
+  #
+  # params:
+  #   - name: page
+  #     description: number of page in pagination
+  #     required: false
+  #     type: Integer
+  #
+  #   - name: limit
+  #     description: number of elements by page in pagination
+  #
+  #   - name: name
+  #     description: name filter
+  # =end
+  def index
+    ...
+  end
+
+== Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/rapidoc.rb

@@ -0,0 +1,62 @@
+require 'handlebars'
+require "rapidoc/config"
+require "rapidoc/version"
+require "tasks/railtie.rb"
+require "rapidoc/routes_doc"
+require "rapidoc/resource_doc"
+require "rapidoc/action_doc"
+require "rapidoc/controller_extractor"
+require "rapidoc/resources_extractor"
+require "rapidoc/param_errors"
+require "rapidoc/templates_generator"
+require "rapidoc/yaml_parser"
+
+module Rapidoc
+
+  include Config
+  include ResourcesExtractor
+  include TemplatesGenerator
+  include ParamErrors
+  include YamlParser
+
+  METHODS = [ "GET", "PUT", "DELETE", "POST" ]
+
+  def create_structure
+    # should be done in this order
+    FileUtils.mkdir target_dir unless File.directory? target_dir
+    FileUtils.mkdir actions_dir unless File.directory? actions_dir
+    FileUtils.cp_r GEM_CONFIG_DIR + "/.", config_dir unless File.directory? config_dir
+    FileUtils.cp_r GEM_ASSETS_DIR, target_dir
+    FileUtils.mkdir examples_dir unless File.directory? examples_dir
+  end
+
+  def remove_structure
+    remove_doc
+    remove_config
+  end
+
+  def remove_config
+    FileUtils.rm_r config_dir if File.directory? config_dir
+  end
+
+  def remove_doc
+    FileUtils.rm_r target_dir if File.directory? target_dir
+  end
+
+  def reset_structure
+    remove_structure
+    create_structure
+  end
+
+  def remove_examples
+    FileUtils.rm_r examples_dir if File.directory? examples_dir
+  end
+
+  def generate_doc
+    resources_doc = get_resources
+
+    generate_index_template( resources_doc )
+    generate_actions_templates( resources_doc )
+  end
+
+end

data/lib/rapidoc/action_doc.rb

@@ -0,0 +1,86 @@
+# encoding: utf-8
+
+require 'rapidoc/http_response'
+require 'json'
+
+module Rapidoc
+
+  ##
+  # This class save information about action of resource.
+  #
+  class ActionDoc
+    attr_reader :resource, :urls, :action, :action_method, :description,
+      :response_formats, :authentication, :params, :file, :http_responses,
+      :errors, :example_res, :example_req
+
+    ##
+    # @param resource [String] resource name
+    # @param action_info [Hash] action info extracted from controller file
+    # @param urls [Array] all urls that call this method
+    #
+    def initialize( routes_info, controller_info, examples_route )
+      @resource         = routes_info[:resource].to_s
+      @action           = routes_info[:action].to_s
+      @action_method    = routes_info[:method].to_s
+      @urls             = routes_info[:urls]
+      @file             = @resource + '_' + @action
+
+      add_controller_info( controller_info ) if controller_info
+      load_examples( examples_route ) if examples_route
+      load_params_errors if default_errors? @action and @params
+    end
+
+    def has_controller_info
+      @controller_info ? true : false
+    end
+
+    private
+
+    def add_controller_info( controller_info )
+      @description      = controller_info["description"]
+      @response_formats = default_response_formats || controller_info["response_formats"]
+      @params           = controller_info["params"]
+      @http_responses   = get_http_responses controller_info["http_responses"]
+      @errors           = controller_info["errors"] ? controller_info["errors"].dup : []
+      @authentication   = get_authentication controller_info["authentication_required"]
+      @controller_info  = true
+    end
+
+    def get_authentication( required_authentication )
+      if [ true, false ].include? required_authentication 
+        required_authentication
+      else
+        default_authentication
+      end
+    end
+
+    def get_http_responses codes
+      codes.map{ |c| HttpResponse.new c } if codes
+    end
+
+    def load_examples( examples_route )
+      return unless File.directory? examples_route + "/"
+      load_request examples_route
+      load_response examples_route
+    end
+
+    def load_params_errors
+      @params.each do |param|
+        @errors << get_error_info( param["name"], "required" ) if param["required"]
+        @errors << get_error_info( param["name"], "inclusion" ) if param["inclusion"]
+      end
+    end
+
+    def load_request( examples_route )
+      file = examples_route + '/' + @resource + '_' + @action + '_request.json'
+      return unless File.exists?( file )
+      File.open( file ){ |f| @example_req = JSON.pretty_generate( JSON.parse(f.read) ) }
+    end
+
+    def load_response( examples_route )
+      file = examples_route + '/' + @resource + '_' + @action + '_response.json'
+      return unless File.exists?( file )
+      File.open( file ){ |f| @example_res = JSON.pretty_generate( JSON.parse(f.read) ) }
+    end
+  end
+end

data/lib/rapidoc/config.rb

@@ -0,0 +1,127 @@
+# encoding: utf-8
+
+module Rapidoc
+
+  ##
+  # This module has all config information about directories and config files.
+  #
+  module Config
+    GEM_CONFIG_DIR = File.join( File.dirname(__FILE__), 'config' )
+    GEM_ASSETS_DIR = File.join( File.dirname(__FILE__), 'templates/assets' )
+    GEM_EXAMPLES_DIR = File.join( File.dirname(__FILE__), 'config/examples')
+
+    @@config = nil
+
+    def gem_templates_dir( f = nil )
+     gem_templates_dir ||= File.join( File.dirname(__FILE__), 'templates' )
+     form_file_name gem_templates_dir, f
+    end
+
+    def config_dir( f = nil )
+      config_dir ||= File.join( ::Rails.root.to_s, 'config/rapidoc' )
+      form_file_name config_dir, f
+    end
+
+    def controller_dir(f = nil)
+      if @@config and @@config['controllers_route']
+        controller_dir = File.join( ::Rails.root.to_s, @@config['controllers_route'] )
+      else
+        controller_dir ||= File.join( ::Rails.root.to_s, 'app/controllers' )
+      end
+
+      form_file_name controller_dir, f
+    end
+
+    def config_file_path
+      config_dir 'rapidoc.yml'
+    end
+
+    def rapidoc_config
+      @@config
+    end
+
+    def load_config
+      if File.exists?( config_file_path )
+        @@config = YAML.load( File.read( config_file_path ) )
+      end
+    end
+
+    def resources_black_list
+      if @@config and @@config['resources_black_list']
+        @@config['resources_black_list'].gsub(' ', '').split(',').map(&:to_sym)
+      else
+        return []
+      end
+    end
+
+    def default_errors?( action )
+      @@config and @@config['default_errors'] == true and
+      [ 'create', 'update' ].include? action
+    end
+
+    def default_authentication
+      if @@config and [ true, false ].include? @@config['default_authentication']
+        @@config['default_authentication']
+      else
+        true
+      end
+    end
+
+    def default_errors
+      @@config and @@config['errors'] ? @@config['errors'] : nil
+    end
+
+    # return the directory where rapidoc generates the doc
+    def target_dir( f = nil )
+      if File.exists?( config_file_path )
+        form_file_name( target_dir_from_config, f )
+      else
+        form_file_name( File.join( ::Rails.root.to_s, 'rapidoc' ), f )
+      end
+    end
+
+    # returns the directory where rapidoc generates actions (html files)
+    def actions_dir( f = nil )
+      f ? target_dir( "actions/#{f}" ) : target_dir( "actions" )
+    end
+
+    # returns the directory where rapidoc searches for examples
+    def examples_dir( f = nil )
+      if File.exists?( config_file_path )
+        form_file_name( examples_dir_from_config_file, f )
+      else
+        form_file_name( config_dir( '/examples' ), f )
+      end
+    end
+
+    def default_response_formats
+      @@config['response_formats'] if @@config
+    end
+
+    private
+
+    def target_dir_from_config
+      if @@config and @@config.has_key?( "doc_route" )
+        File.join(::Rails.root.to_s, @@config['doc_route'] )
+      else
+        File.join(::Rails.root.to_s, 'rapidoc' )
+      end
+    end
+
+    def examples_dir_from_config_file
+      if @@config and @@config.has_key?("examples_route")
+        File.join( ::Rails.root.to_s, @@config["examples_route"] )
+      else
+        config_dir '/examples'
+      end
+    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