ghost_writer 0.0.1 → 0.1.0

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+script: "bundle exec rake spec build"
+rvm:
+  - 1.9.3
+notifications:
+  email:
+    on_success: never

data/README.md

@@ -1,4 +1,5 @@
 # GhostWriter
+[![Build Status](https://travis-ci.org/joker1007/ghost_writer.png)](https://travis-ci.org/joker1007/ghost_writer)
 
 Generate API examples from params and response of controller specs
 
@@ -20,6 +21,18 @@ Or install it yourself as:
 
 Write controller spec:
 ```ruby
+# spec_helper
+RSpec.configure do |config|
+  config.include GhostWriter
+  config.after(:suite) do
+    GhostWriter.generate_api_doc
+  end
+
+  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
+
+# posts_controller_spec
 require 'spec_helper'
 
 describe PostsController do
@@ -28,6 +41,11 @@ describe PostsController do
       get :index
       response.should be_success
     end
+
+    it "should be success", generate_api_doc: "index_error" do # if metadata value is string, use it as filename
+      get :index
+      response.status.should eq 404
+    end
   end
 end
 ```
@@ -40,6 +58,14 @@ GENERATE_API_DOC=1 bundle exec rspec spec
 
 If you don't set environment variable, this gem doesn't generate docs.
 
+## Output Example
+Please look at [output_examples](https://github.com/joker1007/ghost_writer/tree/master/output_examples)
+
+## 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
+
 ## TODO
 - support more output formats (now markdown only)
 

data/lib/ghost_writer.rb

@@ -1,44 +1,58 @@
 require "ghost_writer/version"
+require "ghost_writer/document"
+require "ghost_writer/document_index"
 require "active_support/concern"
 
 module GhostWriter
   extend ActiveSupport::Concern
 
-  mattr_accessor :output_dir
+  module Format
+    autoload "Markdown", "ghost_writer/format/markdown"
+  end
+
+  DOCUMENT_INDEX_FILENAME = "document_index.markdown"
+
+  class << self
+    attr_accessor :output_dir, :github_base_url
 
-  def generate_api_doc
-    @@output_path = @@output_dir ? Rails.root + "doc" + @@output_dir : Rails.root + "doc" + "api_examples"
-    unless File.exist?(doc_dir)
-      FileUtils.mkdir_p(doc_dir)
+    def documents
+      @documents ||= []
+      @documents
     end
 
-    doc = File.open(File.join(doc_dir, "#{doc_name}.markdown"), "w")
+    def generate_api_doc
+      if ENV["GENERATE_API_DOC"]
+        unless File.exist?(output_path)
+          FileUtils.mkdir_p(output_path)
+        end
+        document_index = GhostWriter::DocumentIndex.new(output_path + DOCUMENT_INDEX_FILENAME, documents)
+        document_index.write_file
+        @documents.each(&:write_file)
+        @documents.clear
+      end
+    end
 
-    doc.puts headword("#{described_class} #{doc_name.titleize}", 1)
-    doc.puts headword("access path:", 2)
-    doc.puts quote("#{request.env["REQUEST_METHOD"]} #{request.env["PATH_INFO"]}")
-    doc.puts ""
-    doc.puts headword("request params:", 2)
-    doc.puts quote(controller.params.reject {|key, val| key == "controller" || key == "action"}.inspect, :ruby)
-    doc.puts ""
-    doc.puts headword("status code:", 2)
-    doc.puts quote(response.status.inspect)
-    doc.puts ""
-    doc.puts headword("response:", 2)
-    if controller.params[:format] && controller.params[:format].to_sym == :json
-      puts_json_data(doc)
-    else
-      doc.puts quote(response.body)
+    def output_path
+      output_dir ? Rails.root + "doc" + output_dir : Rails.root + "doc" + "api_examples"
     end
-    doc.puts ""
-    doc.puts "Generated by \"#{example.full_description}\" at #{example.location}"
-    doc.puts ""
-    doc.close
+  end
+
+  def collect_example
+    document = GhostWriter::Document.new(File.join(doc_dir, "#{doc_name}.markdown"), {
+      title: "#{described_class} #{doc_name.titleize}",
+      description: example.full_description.dup,
+      location: example.location.dup,
+      url_example: "#{request.env["REQUEST_METHOD"]} #{request.env["PATH_INFO"]}",
+      param_example: controller.params.reject {|key, val| key == "controller" || key == "action"},
+      status_example: response.status.inspect,
+      response_example: response.body,
+    })
+    GhostWriter.documents << document
   end
 
   private
   def doc_dir
-    @@output_path + described_class.to_s.underscore
+    GhostWriter.output_path + described_class.to_s.underscore
   end
 
   def doc_name
@@ -49,32 +63,10 @@ module GhostWriter
     end
   end
 
-  # TODO: outputのフォーマットを選択可能に
-  def headword(text, level = 1)
-    "#{'#'*level} #{text}\n"
-  end
-
-  def paragraph(text)
-    text + "\n\n"
-  end
-
-  def quote(text, quote_format = nil)
-    "```#{quote_format}\n#{text}\n```"
-  end
-
-  def puts_json_data(doc)
-    data = ActiveSupport::JSON.decode(response.body)
-    if data.is_a?(Array) || data.is_a?(Hash)
-      doc.puts quote(JSON.pretty_generate(data), :javascript)
-    else
-      doc.puts quote(data)
-    end
-  end
-
   included do
     after do
       if example.metadata[:type] == :controller && example.metadata[:generate_api_doc]
-        generate_api_doc if ENV["GENERATE_API_DOC"]
+        collect_example if ENV["GENERATE_API_DOC"]
       end
     end
   end

data/lib/ghost_writer/document.rb

@@ -0,0 +1,71 @@
+class GhostWriter::Document
+  attr_reader :title, :description, :location, :url_example, :param_example, :status_example, :response_example, :output, :relative_path
+
+  def initialize(output, attrs)
+    extend(GhostWriter::Format::Markdown)
+    @output           = output
+    @relative_path    = Pathname.new(output).relative_path_from(GhostWriter.output_path)
+    @title            = attrs[:title]
+    @description      = attrs[:description]
+    @location         = attrs[:location]
+    @url_example      = attrs[:url_example]
+    @param_example    = attrs[:param_example]
+    @status_example   = attrs[:status_example]
+    @response_example = attrs[:response_example]
+  end
+
+  def write_file
+    unless File.exist?(File.dirname(output))
+      FileUtils.mkdir_p(File.dirname(output))
+    end
+    doc = File.open(output, "w")
+
+    doc.write paragraph(<<EOP)
+#{headword(title, 1)}
+EOP
+
+    doc.write paragraph(<<EOP)
+#{headword("access path:", 2)}
+#{quote(url_example)}
+EOP
+
+    doc.write paragraph(<<EOP)
+#{headword("request params:", 2)}
+#{quote(param_example.inspect, :ruby)}
+EOP
+
+    doc.write paragraph(<<EOP)
+#{headword("status code:", 2)}
+#{quote(status_example)}
+EOP
+
+    doc.write paragraph(<<EOP)
+#{headword("response:", 2)}
+#{quote_response(response_example)}
+EOP
+
+    doc.write paragraph(<<EOP)
+"Generated by \"#{description}\" at #{location}"
+EOP
+
+    doc.close
+  end
+
+  private
+  def quote_response(body)
+    if param_example[:format] && param_example[:format].to_sym == :json
+      quote(arrange_json(response_example), :javascript)
+    else
+      quote(response_example, param_example[:format])
+    end
+  end
+
+  def arrange_json(body)
+    data = ActiveSupport::JSON.decode(body)
+    if data.is_a?(Array) || data.is_a?(Hash)
+      JSON.pretty_generate(data)
+    else
+      data
+    end
+  end
+end

data/lib/ghost_writer/document_index.rb

@@ -0,0 +1,30 @@
+class GhostWriter::DocumentIndex
+  attr_reader :output, :documents
+
+  def initialize(output, documents)
+    extend(GhostWriter::Format::Markdown)
+    @output = output
+    @documents = documents
+  end
+
+  def write_file
+    if GhostWriter.github_base_url
+      base_url = GhostWriter.github_base_url + "/"
+    else
+      base_url = ""
+    end
+
+    document_list = documents.map do |document|
+      list(
+        link(document.description, base_url + "#{document.relative_path}")
+      )
+    end
+
+    index_file = File.open(output, "w")
+    index_file.write paragraph(<<EOP)
+#{headword("API Examples")}
+#{document_list.join("\n")}
+EOP
+    index_file.close
+  end
+end

data/lib/ghost_writer/format/markdown.rb

@@ -0,0 +1,27 @@
+module GhostWriter
+  module Format
+    module Markdown
+      private
+      # TODO: outputのフォーマットを選択可能に
+      def headword(text, level = 1)
+        "#{'#'*level} #{text}"
+      end
+
+      def paragraph(text)
+        text + "\n"
+      end
+
+      def quote(text, quote_format = nil)
+        "```#{quote_format}\n#{text}\n```"
+      end
+
+      def list(text, level = 1)
+        "#{"  " * (level - 1)}- #{text}"
+      end
+
+      def link(text, url)
+        "[#{text}](#{url})"
+      end
+    end
+  end
+end

data/lib/ghost_writer/version.rb

@@ -1,3 +1,3 @@
 module GhostWriter
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/output_examples/anonymous_controller/index.markdown

@@ -0,0 +1,24 @@
+# AnonymousController Index
+
+## 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 returns Resources array" at ./spec/lib/ghost_writer_spec.rb:38"
+

data/output_examples/anonymous_controller/show.markdown

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

data/output_examples/document_index.markdown

@@ -0,0 +1,4 @@
+# API Examples
+- [GET /anonymous returns Resources array](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

@@ -28,12 +28,27 @@ describe GhostWriter do
           ]
           render json: collection.as_json
         end
+
+        def show
+          render json: {id: 1, name: "name"}
+        end
+      end
+
+      describe "GET /anonymous" do
+        it "returns Resources array", generate_api_doc: true do
+          begin
+            get :index, param1: "value"
+            response.should be_success
+          rescue Exception => e
+            p e
+          end
+        end
       end
 
-      describe "GET index" do
-        it "should be success", generate_api_doc: true do
+      describe "GET /anonymous/1.json" do
+        it "returns a Resource json", generate_api_doc: true do
           begin
-            get :index
+            get :show, id: 1, format: :json, param1: "value", params2: ["value1", "value2"]
             response.should be_success
           rescue Exception => e
             p e
@@ -59,17 +74,30 @@ describe GhostWriter do
 
       it "generate api doc file" 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/
+      end
+
+      context "Given github_base_url" do
+        let(:github_base_url) { "https://github.com/joker1007/ghost_writer/tree/master/output_examples" }
+        it "create index file written github links" do
+          GhostWriter.github_base_url = github_base_url
+          group.run(NullObject.new)
+          GhostWriter.generate_api_doc
+          File.read(Rails.root + "doc" + "api_examples" + GhostWriter::DOCUMENT_INDEX_FILENAME).should =~ /#{github_base_url}/
+        end
       end
     end
 
-    context 'ENV["GENERATE_API_DOC"] is true' do
+    context 'ENV["GENERATE_API_DOC"] is false' do
       before do
         ENV["GENERATE_API_DOC"] = nil
       end
 
       it "does not generate api doc file" do
         group.run(NullObject.new)
+        GhostWriter.generate_api_doc
         File.exist?(Rails.root + "doc" + "api_examples" + "anonymous_controller" + "index.markdown").should be_false
       end
     end
@@ -91,7 +119,9 @@ describe GhostWriter do
     it "generate api doc file" do
       ENV["GENERATE_API_DOC"] = "1"
       group.run(NullObject.new)
+      GhostWriter.generate_api_doc
       File.exist?(Rails.root + "doc" + output_dir + "anonymous_controller" + "index.markdown").should be_true
+      File.read(Rails.root + "doc" + output_dir + "anonymous_controller" + "index.markdown").should =~ /# AnonymousController Index/
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ghost_writer
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-08 00:00:00.000000000 Z
+date: 2013-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -99,13 +99,20 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - ghost_writer.gemspec
 - lib/ghost_writer.rb
+- lib/ghost_writer/document.rb
+- lib/ghost_writer/document_index.rb
+- lib/ghost_writer/format/markdown.rb
 - lib/ghost_writer/version.rb
+- output_examples/anonymous_controller/index.markdown
+- output_examples/anonymous_controller/show.markdown
+- output_examples/document_index.markdown
 - spec/lib/ghost_writer_spec.rb
 - spec/rails_app/.gitignore
 - spec/rails_app/README.rdoc
@@ -160,7 +167,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1116131178365198946
+      hash: 2108698769650766932
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -169,7 +176,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1116131178365198946
+      hash: 2108698769650766932
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23