rapidoc 0.0.4 → 0.0.5

data/README.rdoc

@@ -1,23 +1,21 @@
 = Rapidoc
 
-REST API documentation generator for rails projects ( 0.04 version ).
+REST API documentation generator for rails projects ( 0.05 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.
+It uses routes information, rapidoc comments and json examples for generate
+static html files. Documentation templates are generated using _handlebars_ and
+_bootstrap_.
 
-This is how the web interface look like:
+This is how the web interface look like: example[http://drinor.github.io/rapidoc/index.html]
 
-* 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
+Rapidoc is based in restapi_doc[https://github.com/Alayho/restapi_doc] gem.
 
 == Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'rapidoc', :git => 'https://github.com/drinor/rapidoc.git'
+    gem 'rapidoc'
 
 And then execute:
 
@@ -33,30 +31,6 @@ 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.
@@ -73,37 +47,7 @@ For get action documentation you need add an action block to resource controller
 
 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
+== Documentation example
 
 Resource documentation:
 
@@ -143,6 +87,44 @@ Action documentation:
     ...
   end
 
+== 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 in the documentation.
+
+The *doc_route* parameter let you specify where _rapidoc_ will generate the
+documentation:
+
+  path_project/doc
+
+The *examples_route* parameter let you specify where _rapidoc_ will search for
+requests/responeses examples files:
+
+  path_project/examples
+
+For more details and options please visit the Wiki[https://github.com/drinor/rapidoc/wiki].
+
+== Other Options
+
+* You can use .yml files for write documentation blocks ( configuration[https://github.com/drinor/rapidoc/wiki/Configuration] ).
+
+* Rapidoc let you define *json* files with requests/responses examples ( examples[https://github.com/drinor/rapidoc/wiki/Request---Response-Examples] )
+
+* Rapidoc let you use default errors ( errors[https://github.com/drinor/rapidoc/wiki/Params-Errors] )
+
+* Rapidoc has a lot of parameters for document actions of resource ( actions[https://github.com/drinor/rapidoc/wiki/Action-Documentation] )
+
+* When you are in an action page, you can click the resource name and go back to the resources page with resource selected.
+
+* If there is an error in your documentation, rapidoc show you an error message with the file name that contains the error and block lines.
+
 == Contributing
 
 1. Fork it

data/lib/rapidoc/config.rb

@@ -32,6 +32,10 @@ module Rapidoc
       form_file_name controller_dir, f
     end
 
+    def controllers_extension
+      ( @@config and @@config['controllers_route'] ) ? '.yml' : '.rb'
+    end
+
     def config_file_path
       config_dir 'rapidoc.yml'
     end

data/lib/rapidoc/controller_extractor.rb

@@ -17,8 +17,8 @@ module Rapidoc
       lines = IO.readlines( controller_dir( controller_file ) )
       blocks = extract_blocks( lines )
 
-      @resource_info = YamlParser.extract_resource_info( lines, blocks )
-      @actions_info = YamlParser.extract_actions_info( lines, blocks )
+      @resource_info = YamlParser.extract_resource_info( lines, blocks, controller_file )
+      @actions_info = YamlParser.extract_actions_info( lines, blocks, controller_file )
     end
 
     def get_actions_info

data/lib/rapidoc/resource_doc.rb

@@ -16,7 +16,7 @@ module Rapidoc
     #
     def initialize( resource_name, routes_actions_info )
       @name = resource_name.to_s
-      @controller_file = name.to_s.pluralize + '_controller.rb'
+      @controller_file = name.to_s.pluralize + '_controller' + controllers_extension
 
       generate_info routes_actions_info
     end
@@ -38,6 +38,9 @@ module Rapidoc
         extractor = get_controller_extractor
         @description = extractor.get_resource_info['description'] if extractor
         @actions_doc =  get_actions_doc( routes_info, extractor )
+
+        # template need that description will be an array
+        @description = [ @description ] unless @description.class == Array
       end
     end
 

data/lib/rapidoc/templates/action.html.hbs

@@ -39,7 +39,7 @@
 
     <div class="container">
       <div class="page-header">
-        <h1>{{action.resource}}</h1>
+        <h1><a href="../index.html?collapse=collapse{{action.resource}}">{{action.resource}}</a></h1>
       </div>
 
       <ul class="nav nav-tabs" id="myTab">

data/lib/rapidoc/templates/index.html.hbs

@@ -27,8 +27,8 @@
           <a class="brand" href="#">{{info.project_name}}</a>
           <div class="nav-collapse">
             <ul class="nav">
-              <li class="active"><a href="#">Resources</a></li>
-              <li><a target="_blank" href="https://github.com/drinor/rapidoc.git">Contact</a></li>
+              <li class="active"><a href="index.html">Resources</a></li>
+              <li><a href="https://github.com/drinor/rapidoc.git">Contact</a></li>
             </ul>
           </div>
         </div>
@@ -51,7 +51,9 @@
           <div id="collapse{{this.simple_name}}" class="accordion-body collapse">
             <div class="accordion-inner">
               <div class="pad-description">
-                {{this.description}}
+                {{#each this.description}}
+                  <p>{{this}}</p>
+                {{/each}}
               </div>
               <table class="table table-hover">
               {{#each this.actions_doc}}
@@ -80,6 +82,14 @@
       <footer>
         <p>{{info.company}} {{info.year}}</p>
       </footer>
+
+      <script>
+        window.onload = function () { 
+          var collapse = '#' + decodeURI( (RegExp(name + '=' + '(.+?)(&|$)').exec(location.search)||[,null])[1] );
+          console.log(collapse)
+          $(collapse).collapse('show')
+        }
+      </script>
     </div>
   </body>
 </html>

data/lib/rapidoc/version.rb

@@ -1,3 +1,3 @@
 module Rapidoc
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/lib/rapidoc/yaml_parser.rb

@@ -12,13 +12,18 @@ module Rapidoc
     # @param blocks [Hash] lines of blocks, example: { init: 1, end: 4 }
     # @return [Hash] resource info
     #
-    def extract_resource_info( lines, blocks )
+    def extract_resource_info( lines, blocks, file_name )
       blocks ? info = [] : blocks = []
 
       blocks.each.map do |b|
         if lines[ b[:init] ].include? "=begin resource"
           n_lines = b[:end] - b[:init] - 1
-          info.push YAML.load( lines[ b[:init] +1, n_lines ].join.gsub(/\ *#/, '') )
+          
+          begin
+            info.push YAML.load( lines[ b[:init] +1, n_lines ].join.gsub(/\ *#/, '') )
+          rescue SyntaxError => e
+            puts "Error parsing block in #{file_name} file [#{b[:init]} - #{b[:end]}]"
+          end
         end
       end
 
@@ -32,14 +37,19 @@ module Rapidoc
     # @param blocks [Hash] lines of blocks, example: { init: 1, end: 4 }
     # @return [Array] all actions info
     #
-    def extract_actions_info( lines, blocks )
+    def extract_actions_info( lines, blocks, file_name )
       info = []
       blocks = [] unless blocks
 
-      blocks.each do |block|
-        if lines[ block[:init] ].include? "=begin action"
-          n_lines = block[:end] - block[:init] - 1
-          info << YAML.load( lines[ block[:init] + 1, n_lines ].join.gsub(/\ *#/, '') )
+      blocks.each do |b|
+        if lines[ b[:init] ].include? "=begin action"
+          n_lines = b[:end] - b[:init] - 1
+          
+          begin
+            info << YAML.load( lines[ b[:init] + 1, n_lines ].join.gsub(/\ *#/, '') )
+          rescue SyntaxError => e
+            puts "Error parsing block in #{file_name} file [#{b[:init]} - #{b[:end]}]"
+          end
         end
       end
 

data/spec/features/index_spec.rb

@@ -57,7 +57,9 @@ describe "Index page" do
 
     it "contains the correct description" do
       @resources.each do |resource|
-        page.should have_text(resource.description)
+        resource.description.each do |paragraph|
+          page.should have_text( paragraph )
+        end
       end
     end
   end

data/spec/lib/controller_extractor_spec.rb

@@ -73,5 +73,26 @@ describe ControllerExtractor do
       lambda{ ControllerExtractor.new( "no_file" ) }.should raise_error
     end
   end
+
+  context "when check controllers_name" do
+    context "when use default controllers route" do
+      it "use .rb extension for controllers files" do
+        ResourceDoc.any_instance.stub( :generate_info ).and_return( true )
+        resource_doc = ResourceDoc.new( 'user', nil )
+        resource_doc.controller_file.should == "users_controller.rb"
+      end
+    end
+
+    context "when use custom controllers route" do
+      it "use .yml extension for controllers files" do
+        File.open( config_file_path, 'w') { |file| file.write "controllers_route: \"vim\"" }
+        load_config
+
+        ResourceDoc.any_instance.stub( :generate_info ).and_return( true )
+        resource_doc = ResourceDoc.new( 'user', nil )
+        resource_doc.controller_file.should == "users_controller.yml"
+      end
+    end
+  end
 end
 

data/spec/lib/rake_spec.rb

@@ -1,6 +1,17 @@
 require 'spec_helper'
 require 'rake'
 
+def capture_stdout(&block)
+  original_stdout = $stdout
+  $stdout = fake = StringIO.new
+  begin
+    yield
+  ensure
+    $stdout = original_stdout
+  end
+  fake.string
+end
+
 describe Rake do
   context 'rapidoc:generate' do
     before do
@@ -18,7 +29,10 @@ describe Rake do
     end
 
     it "should create documentation" do
-      run_rake_task
+      output = capture_stdout { run_rake_task }
+      output.should be_include( 'Generating API documentation...' )
+      output.should be_include( 'Completed API documentation generation' )
+
       File.exists?( ::Rails.root.to_s + "/rapidoc/index.html" ).should == true
     end
   end

data/spec/lib/resource_doc_spec.rb

@@ -109,23 +109,42 @@ describe ResourceDoc do
   end
 
   context "when create new valid instance" do
-    before :all do
-      @resource_name = "users"
-      @rdoc = ResourceDoc.new @resource_name, @routes_actions_info
-    end
+    context "when use normal sintax" do
+      before :all do
+        @resource_name = "users"
+        @rdoc = ResourceDoc.new @resource_name, @routes_actions_info
+      end
 
-    it "saves it correctly" do
-      @rdoc.name.should == @resource_name
-      @rdoc.controller_file.should == @resource_name + '_controller.rb'
-    end
+      it "saves it correctly" do
+        @rdoc.name.should == @resource_name
+        @rdoc.controller_file.should == @resource_name + '_controller.rb'
+      end
 
-    it "set correct description" do
-      @rdoc.description.should == @extractor.get_resource_info['description']
+      it "set correct description" do
+        @rdoc.description.should == [ @extractor.get_resource_info['description'] ]
+      end
+
+      it "set correct actions_doc" do
+        @rdoc.actions_doc.class.should == Array
+        @rdoc.actions_doc.each{ |ad| ad.class.should == ActionDoc }
+      end
     end
 
-    it "set correct actions_doc" do
-      @rdoc.actions_doc.class.should == Array
-      @rdoc.actions_doc.each{ |ad| ad.class.should == ActionDoc }
+    context "when description is an array" do
+      before :all do
+        @file_name = controller_dir 'resources_controller.rb'
+        content = "# =begin resource\n# description:\n#   - Info1\n#   - Info2\n# =end\n"
+        File.open( @file_name, 'w') { |file| file.write content }
+        @rdoc = ResourceDoc.new "resource", []
+      end
+
+      after :all do
+        File.delete( @file_name )
+      end
+
+      it "set correct description" do
+        @rdoc.description.should == [ 'Info1', 'Info2' ]
+      end
     end
   end
 end

data/spec/lib/yaml_parser_spec.rb

@@ -0,0 +1,102 @@
+require "spec_helper"
+
+include Rapidoc
+
+def capture_stdout(&block)
+  original_stdout = $stdout
+  $stdout = fake = StringIO.new
+  begin
+    yield
+  ensure
+    $stdout = original_stdout
+  end
+  fake.string
+end
+
+describe Rapidoc::YamlParser do
+
+  before :all do
+    @description = "resource description"
+    @action1 = "index"
+    @action2 = "create"
+    @blocks = [ { init: 0, end: 2 }, { init: 4, end: 6 }, { init: 8, end: 10 } ]
+    @lines = [
+      "  # =begin resource\n",
+      "  # description: #{@description}\n",
+      "  # =end\n",
+      "  ...\n",
+      "  # =begin action\n",
+      "  # action: #{@action1}\n",
+      "  # =end\n",
+      "  ...\n",
+      "  # =begin action\n",
+      "  # action: #{@action2}\n",
+      "  # =end\n"
+    ]
+  end
+
+  context "when call extract_resource_info" do
+    context "when block is correct" do
+      before :all do
+        @resource_info = extract_resource_info( @lines, @blocks, 'file' )
+      end
+
+      it "returns resource info" do
+        @resource_info.keys.should be_include( "description" )
+      end
+
+      it "return correct description" do
+        @resource_info['description'].should == @description
+      end
+    end
+
+    context "when there is an error in the block" do
+      before :all do
+        @blocks2 = [ { init: 0, end: 2 } ]
+        @lines2 = [
+          "  # =begin resource\n",
+          "  # description: hello : goodbye\n",
+          "  # =end\n"
+        ]
+      end
+
+      it "prints error message" do
+        output = capture_stdout { extract_resource_info( @lines2, @blocks2, 'file' ) }
+        output.should == "Error parsing block in file file [0 - 2]\n"
+      end
+    end
+  end
+
+  context "when call extract_actions_info" do
+    context "when block is correct" do
+      before :all do
+        @actions_info = extract_actions_info( @lines, @blocks, 'file' )
+      end
+
+      it "returns all actions info" do
+        @actions_info.size.should == 2
+      end
+
+      it "returns correct info of each action" do
+        @actions_info.first['action'].should == @action1
+        @actions_info.last['action'].should == @action2
+      end
+    end
+
+    context "when there is an error in the block" do
+      before :all do
+        @blocks2 = [ { init: 0, end: 2 } ]
+        @lines2 = [
+          "  # =begin action\n",
+          "  # action: hello : goodbye\n",
+          "  # =end\n"
+        ]
+      end
+
+      it "prints error message" do
+        output = capture_stdout { extract_actions_info( @lines2, @blocks2, 'file' ) }
+        output.should == "Error parsing block in file file [0 - 2]\n"
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rapidoc
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-31 00:00:00.000000000 Z
+date: 2013-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -207,7 +207,7 @@ files:
 - spec/lib/resources_extractor_spec.rb
 - spec/lib/routes_doc_spec.rb
 - spec/lib/templates_generator_spec.rb
-- spec/lib/yard_parser_spec.rb
+- spec/lib/yaml_parser_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/drinor/rapidoc.git
 licenses: []
@@ -221,18 +221,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 2741643923882514570
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 2741643923882514570
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25
@@ -303,5 +297,5 @@ test_files:
 - spec/lib/resources_extractor_spec.rb
 - spec/lib/routes_doc_spec.rb
 - spec/lib/templates_generator_spec.rb
-- spec/lib/yard_parser_spec.rb
+- spec/lib/yaml_parser_spec.rb
 - spec/spec_helper.rb

data/spec/lib/yard_parser_spec.rb

@@ -1,55 +0,0 @@
-require "spec_helper"
-
-include Rapidoc
-
-describe Rapidoc::YamlParser do
-
-  before :all do
-    @description = "resource description"
-    @action1 = "index"
-    @action2 = "create"
-    @blocks = [ { init: 0, end: 2 }, { init: 4, end: 6 }, { init: 8, end: 10 } ]
-    @lines = [ 
-      "  # =begin resource\n",
-      "  # description: #{@description}\n",
-      "  # =end\n",
-      "  ...\n",
-      "  # =begin action\n",
-      "  # action: #{@action1}\n",
-      "  # =end\n",
-      "  ...\n",
-      "  # =begin action\n",
-      "  # action: #{@action2}\n",
-      "  # =end\n" 
-    ]
-  end
-
-  context "when call extract_resource_info" do
-    before :all do
-      @resource_info = extract_resource_info( @lines, @blocks )
-    end
-
-    it "returns resource info" do
-      @resource_info.keys.should be_include( "description" )
-    end
-
-    it "return correct description" do
-      @resource_info['description'].should == @description
-    end
-  end
-
-  context "when call extract_actions_info" do
-    before :all do
-      @actions_info = extract_actions_info( @lines, @blocks )
-    end
-
-    it "returns all actions info" do
-      @actions_info.size.should == 2
-    end
-
-    it "returns correct info of each action" do
-      @actions_info.first['action'].should == @action1
-      @actions_info.last['action'].should == @action2
-    end
-  end
-end