ghost_writer 0.1.1 → 0.2.0

data/README.md

@@ -21,14 +21,12 @@ Or install it yourself as:
 ## Usage
 
 Write controller spec:
+
+**Caution: Using ghost_writer command and Defining after fook manually at the same time, after hook is executed twice, because of it document_index is cleared.**
 ```ruby
 # spec_helper
 RSpec.configure do |config|
-  config.include GhostWriter
-  config.after(:suite) do
-    GhostWriter.generate_api_doc
-  end
-
+  # The difference with previous version. already no need including Module and Defining after hook
   GhostWriter.output_dir = "api_docs" # Optional (default is "api_examples")
   GhostWriter.github_base_url = "https://github.com/joker1007/ghost_writer/tree/master/output_examples" # Optional
 end
@@ -53,7 +51,7 @@ end
 
 And set environment variable GENERATE_API_DOC at runtime
 ```
-GENERATE_API_DOC=1 bundle exec rspec spec
+bundle exec ghost_writer spec/controllers
 -> generate docs at [Rails.root]/doc/api_examples
 ```
 
@@ -65,7 +63,7 @@ Please look at [output_examples](https://github.com/joker1007/ghost_writer/tree/
 ## Config
 If output_dir is set, generate docs at `[Rails.root]/doc/[output_dir]`
 
-If github_base_url is set, link index is based on the url, like output_examples
+If github\_base\_url is set, link index is based on the url, like output\_examples
 
 ## TODO
 - support more output formats (now markdown only)

data/bin/ghost_writer

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+
+require "trollop"
+require "rspec"
+require "ghost_writer"
+
+GhostWriter.output_flag = true
+
+parser = Trollop::Parser.new do
+  version "ghost_writer v#{GhostWriter::VERSION}"
+  banner <<-EOS
+Generate API Examples using Controller spec parameters.
+
+Usage:
+       ghost_writer [options] <spec file or directory>
+
+where [options] are:
+EOS
+
+  opt :output, "Output directory", :type => String
+  opt :clear, "[Caution] Clear Output directory before running specs", :default => false
+end
+
+opts = Trollop::with_standard_exception_handling parser do
+  raise Trollop::HelpNeeded if ARGV.empty?
+  parser.parse ARGV
+end
+
+RSpec.configure do |c|
+  c.include GhostWriter
+  GhostWriter.output_dir = opts[:output]
+  c.after(:suite) do
+    GhostWriter.generate_api_doc
+  end
+end
+
+if opts[:clear]
+  cmd = "rm -rf doc/#{GhostWriter.output_dir}"
+  puts cmd
+  system(cmd)
+end
+
+require "rspec/autorun"

data/ghost_writer.gemspec

@@ -19,8 +19,10 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency "activesupport", ">= 3.0.0"
   gem.add_dependency "rspec-rails", "~> 2.11"
+  gem.add_dependency "trollop"
 
   gem.add_development_dependency "rspec", "~> 2.12"
   gem.add_development_dependency 'rake', ['>= 0']
   gem.add_development_dependency 'rails', ['~> 3.2.9']
+  gem.add_development_dependency 'tapp'
 end

data/lib/ghost_writer/document.rb

@@ -14,38 +14,52 @@ class GhostWriter::Document
     @response_example = attrs[:response_example]
   end
 
-  def write_file
+  def write_file(overwrite = false)
     unless File.exist?(File.dirname(output))
       FileUtils.mkdir_p(File.dirname(output))
     end
-    doc = File.open(output, "w")
 
-    doc.write paragraph(<<EOP)
+    mode = overwrite ? "w" : "a"
+    doc = File.open(output, mode)
+
+    if overwrite
+      doc.write paragraph(<<EOP)
 #{headword(title, 1)}
+
+--------------------------------
+
+EOP
+    end
+
+    doc.write paragraph(<<EOP)
+#{headword(description, 2)}
 EOP
 
     doc.write paragraph(<<EOP)
-#{headword("access path:", 2)}
+#{headword("access path:", 3)}
 #{quote(url_example)}
 EOP
 
     doc.write paragraph(<<EOP)
-#{headword("request params:", 2)}
+#{headword("request params:", 3)}
 #{quote(param_example.inspect, :ruby)}
 EOP
 
     doc.write paragraph(<<EOP)
-#{headword("status code:", 2)}
+#{headword("status code:", 3)}
 #{quote(status_example)}
 EOP
 
     doc.write paragraph(<<EOP)
-#{headword("response:", 2)}
+#{headword("response:", 3)}
 #{quote_response(response_example)}
 EOP
 
     doc.write paragraph(<<EOP)
-"Generated by \"#{description}\" at #{location}"
+Generated by "#{description}\" at #{location}
+
+--------------------------------
+
 EOP
 
     doc.close

data/lib/ghost_writer/document_index.rb

@@ -14,10 +14,12 @@ class GhostWriter::DocumentIndex
       base_url = ""
     end
 
-    document_list = documents.map do |document|
-      list(
-        link(document.description, base_url + "#{document.relative_path}")
-      )
+    document_list = documents.flat_map do |output, docs|
+      docs.map do |d|
+        list(
+          link(d.description, base_url + "#{d.relative_path}")
+        )
+      end
     end
 
     index_file = File.open(output, "w")

data/lib/ghost_writer/version.rb

@@ -1,3 +1,3 @@
 module GhostWriter
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/ghost_writer.rb

@@ -10,35 +10,51 @@ module GhostWriter
     autoload "Markdown", "ghost_writer/format/markdown"
   end
 
+  DEFAULT_OUTPUT_DIR = "api_examples"
   DOCUMENT_INDEX_FILENAME = "document_index.markdown"
 
   class << self
-    attr_accessor :output_dir, :github_base_url
+    attr_writer :output_dir, :output_flag
+    attr_accessor :github_base_url
 
-    def documents
-      @documents ||= []
-      @documents
+    def document_group
+      @document_group ||= {}
+      @document_group
     end
 
     def generate_api_doc
-      if ENV["GENERATE_API_DOC"]
+      if output_flag
         unless File.exist?(output_path)
           FileUtils.mkdir_p(output_path)
         end
-        document_index = GhostWriter::DocumentIndex.new(output_path + DOCUMENT_INDEX_FILENAME, documents)
+        document_index = GhostWriter::DocumentIndex.new(output_path + DOCUMENT_INDEX_FILENAME, document_group)
         document_index.write_file
-        @documents.each(&:write_file)
-        @documents.clear
+        document_group.each do |output, docs|
+          docs.sort_by!(&:description)
+          docs.shift.write_file(true)
+          docs.each(&:write_file)
+        end
+
+        document_group.clear
       end
     end
 
+    def output_flag
+      !!(@output_flag ? @output_flag : ENV["GENERATE_API_DOC"])
+    end
+
+    def output_dir
+      @output_dir ? @output_dir : DEFAULT_OUTPUT_DIR
+    end
+
     def output_path
-      output_dir ? Rails.root + "doc" + output_dir : Rails.root + "doc" + "api_examples"
+      Rails.root + "doc" + output_dir
     end
   end
 
   def collect_example
-    document = GhostWriter::Document.new(File.join(doc_dir, "#{doc_name}.markdown"), {
+    output = File.join(doc_dir, "#{doc_name}.markdown")
+    document = GhostWriter::Document.new(output, {
       title: "#{described_class} #{doc_name.titleize}",
       description: example.full_description.dup,
       location: example.location.dup,
@@ -47,7 +63,8 @@ module GhostWriter
       status_example: response.status.inspect,
       response_example: response.body,
     })
-    GhostWriter.documents << document
+    GhostWriter.document_group[output] ||= []
+    GhostWriter.document_group[output] << document
   end
 
   private
@@ -66,7 +83,7 @@ module GhostWriter
   included do
     after do
       if example.metadata[:type] == :controller && example.metadata[:generate_api_doc]
-        collect_example if ENV["GENERATE_API_DOC"]
+        collect_example if GhostWriter.output_flag
       end
     end
   end

data/output_examples/anonymous_controller/index.markdown

@@ -1,24 +1,59 @@
 # AnonymousController Index
 
-## access path:
+--------------------------------
+
+
+## GET /anonymous first spec
+
+### access path:
 ```
 GET /anonymous
 ```
 
-## request params:
+### request params:
 ```ruby
 {"param1"=>"value"}
 ```
 
-## status code:
+### status code:
 ```
 200
 ```
 
-## response:
+### response:
 ```
 [{"id":1,"name":"name"},{"id":2,"name":"name"}]
 ```
 
-"Generated by "GET /anonymous returns Resources array" at ./spec/lib/ghost_writer_spec.rb:38"
+Generated by "GET /anonymous first spec" at ./spec/lib/ghost_writer_spec.rb:38
+
+--------------------------------
+
+
+## GET /anonymous second spec
+
+### access path:
+```
+GET /anonymous
+```
+
+### request params:
+```ruby
+{"param1"=>"value"}
+```
+
+### status code:
+```
+200
+```
+
+### response:
+```
+[{"id":1,"name":"name"},{"id":2,"name":"name"}]
+```
+
+Generated by "GET /anonymous second spec" at ./spec/lib/ghost_writer_spec.rb:47
+
+--------------------------------
+
 

data/output_examples/anonymous_controller/show.markdown

@@ -1,21 +1,26 @@
 # AnonymousController Show
 
-## access path:
+--------------------------------
+
+
+## GET /anonymous/1.json returns a Resource json
+
+### access path:
 ```
 GET /anonymous/1.json
 ```
 
-## request params:
+### request params:
 ```ruby
 {"param1"=>"value", "params2"=>["value1", "value2"], "id"=>"1", "format"=>"json"}
 ```
 
-## status code:
+### status code:
 ```
 200
 ```
 
-## response:
+### response:
 ```javascript
 {
   "id": 1,
@@ -23,5 +28,8 @@ GET /anonymous/1.json
 }
 ```
 
-"Generated by "GET /anonymous/1.json returns a Resource json" at ./spec/lib/ghost_writer_spec.rb:49"
+Generated by "GET /anonymous/1.json returns a Resource json" at ./spec/lib/ghost_writer_spec.rb:58
+
+--------------------------------
+
 

data/output_examples/document_index.markdown

@@ -1,4 +1,5 @@
 # API Examples
-- [GET /anonymous returns Resources array](https://github.com/joker1007/ghost_writer/tree/master/output_examples/anonymous_controller/index.markdown)
+- [GET /anonymous first spec](https://github.com/joker1007/ghost_writer/tree/master/output_examples/anonymous_controller/index.markdown)
+- [GET /anonymous second spec](https://github.com/joker1007/ghost_writer/tree/master/output_examples/anonymous_controller/index.markdown)
 - [GET /anonymous/1.json returns a Resource json](https://github.com/joker1007/ghost_writer/tree/master/output_examples/anonymous_controller/show.markdown)
 

data/spec/lib/ghost_writer_spec.rb

@@ -35,7 +35,16 @@ describe GhostWriter do
       end
 
       describe "GET /anonymous" do
-        it "returns Resources array", generate_api_doc: true do
+        it "first spec", generate_api_doc: true do
+          begin
+            get :index, param1: "value"
+            response.should be_success
+          rescue Exception => e
+            p e
+          end
+        end
+
+        it "second spec", generate_api_doc: true do
           begin
             get :index, param1: "value"
             response.should be_success
@@ -60,10 +69,7 @@ describe GhostWriter do
 
   context "Not given output_dir" do
     before do
-      clear_output("api_examples")
-    end
-
-    after do
+      GhostWriter.output_dir = nil
       clear_output("api_examples")
     end
 
@@ -76,7 +82,10 @@ describe GhostWriter do
         group.run(NullObject.new)
         GhostWriter.generate_api_doc
         File.exist?(Rails.root + "doc" + "api_examples" + "anonymous_controller" + "index.markdown").should be_true
-        File.read(Rails.root + "doc" + "api_examples" + "anonymous_controller" + "index.markdown").should =~ /# AnonymousController Index/
+        doc_body = File.read(Rails.root + "doc" + "api_examples" + "anonymous_controller" + "index.markdown")
+        doc_body.should =~ /# AnonymousController Index/
+        doc_body.should =~ /first spec/
+        doc_body.should =~ /second spec/
       end
 
       context "Given github_base_url" do
@@ -113,7 +122,6 @@ describe GhostWriter do
 
     after do
       GhostWriter.output_dir = nil
-      clear_output(output_dir)
     end
 
     it "generate api doc file" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ghost_writer
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-18 00:00:00.000000000 Z
+date: 2013-02-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -43,6 +43,22 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '2.11'
+- !ruby/object:Gem::Dependency
+  name: trollop
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -91,10 +107,27 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 3.2.9
+- !ruby/object:Gem::Dependency
+  name: tapp
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Generate API examples from params and response of controller specs
 email:
 - kakyoin.hierophant@gmail.com
-executables: []
+executables:
+- ghost_writer
 extensions: []
 extra_rdoc_files: []
 files:
@@ -104,6 +137,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- bin/ghost_writer
 - ghost_writer.gemspec
 - lib/ghost_writer.rb
 - lib/ghost_writer/document.rb
@@ -167,7 +201,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2436984307325709434
+      hash: 885870710401004349
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -176,7 +210,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2436984307325709434
+      hash: 885870710401004349
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23