grape-doc 0.0.1.alpha → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6cc913997d475f2662a9a46193ef7a20f09a6512
-  data.tar.gz: d424ec6fd9bf1bbaf98c077f734ae3cf68ebd9cf
+  metadata.gz: 78159d4d2d7852fadb62e8caf6b7aad1dbd0f772
+  data.tar.gz: 4fcba1b40c4a766cfb9d2d06e48e2563c75bd6b1
 SHA512:
-  metadata.gz: 9e65db9a8cd40cf01d25116f2432791f235c3fef9d8b7dafaeb3ae715d554478b72c4ae0645ff81e7e50d25ea799fa4fae8b16c3cd20eed443239946597211a9
-  data.tar.gz: e4c5014b787461dde2e770b3f50975f9b6ba50afcd0eee15768856f6735efa3e34cd7aa647dc272ca8fcdcc9d3ad6ba5d3ce0b034ebd5032cdb34308371d46ac
+  metadata.gz: b7780a35011633490200162fda618beb50ff8e82052c631690b99927fd82c4380d21d05a2fca12080373e32fc39b0041aaba4f2c067c8cc0142371c183991f22
+  data.tar.gz: 193c15ecde4b52289c5148b1b84aa4859f5561319b84c55ffcc7e40f1d2189962fb6e8632f0b62feab0c65e86ed54b2911be75fa3c2d64c6997f45ec4bfa1cf6

data/Gemfile

@@ -1,2 +1,2 @@
 source :rubygems
-gemspec
+gemspec

data/VERSION

@@ -1 +1 @@
-0.0.1.alpha
+0.1.0

data/grape-doc.gemspec

@@ -20,7 +20,9 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake"
 
   spec.add_dependency "grape"
+  spec.add_dependency "loader"
+  spec.add_dependency "RedCloth"
   spec.add_dependency "rack-test"
-  spec.add_dependency "rack-test-poc"
+  spec.add_dependency "rack-test-poc",">= 1.0.2"
 
 end

data/lib/grape/doc/doc_class/header.rb

@@ -0,0 +1,30 @@
+module GrapeDoc
+  class ApiDocParts
+
+    class H1 < StringObject
+    end
+
+    class H2 < H1
+    end
+
+    class H3 < H1
+    end
+
+    class H4 < H1
+    end
+
+    class H5 < H1
+    end
+
+    class H6 < H1
+    end
+
+    class Block < StringObject
+      self.markdown = "bq"
+    end
+
+    class Br < StringBasic
+    end
+
+  end
+end

data/lib/grape/doc/doc_class/link.rb

@@ -0,0 +1,22 @@
+module GrapeDoc
+  class ApiDocParts
+
+    class Link < StringObject
+
+      def initialize(text,url)
+        super(text)
+        @url = url
+      end
+
+      def to_textile
+        "\"#{self}\":#{@url}"
+      end
+
+    end
+
+    class PictureLink < StringObjectEnded
+      self.markdown = '!'
+    end
+
+  end
+end

data/lib/grape/doc/doc_class/list.rb

@@ -0,0 +1,34 @@
+module GrapeDoc
+  class ApiDocParts
+
+    class List < ArrayObject
+
+      self.markdown = '*'
+
+      def initialize(obj)
+        obj = case obj
+                when Array
+                  obj
+
+                when String,Symbol
+                  obj.to_s.split("\n")
+
+                else
+                  raise(ArgumentError,'unknown format given for list object')
+
+              end
+
+        super(obj)
+
+      end
+
+    end
+
+    class NumericalList < List
+      self.markdown = '#'
+    end
+
+
+
+  end
+end

data/lib/grape/doc/doc_class/parser.rb

@@ -0,0 +1,56 @@
+module GrapeDoc
+  class ApiDocParts
+
+    module Parser
+      class << self
+
+        def parse(object)
+          case object
+
+            when Array
+              object.map{|e|
+                case e
+                  when Array
+                    e.dup
+
+                  else
+                    self.format_parse(*e)
+
+                end
+              }
+
+            else
+              # self.format_parse(object)
+              object
+
+          end
+        end
+
+        def format_parse(text,*args)
+          text = text.dup.to_s
+          args.each do |command|
+            case command.to_s.downcase
+
+              when /^bold/
+                text.replace("*#{text}*")
+
+              when /^italic/
+                text.replace("__#{text}__")
+
+              when /^underlined/
+                text.replace("+#{text}+")
+
+              when /^superscript/
+                text.replace("^#{text}^")
+
+            end
+          end;return text
+
+        end
+
+
+      end
+    end
+
+  end
+end

data/lib/grape/doc/doc_class/raw.rb

@@ -0,0 +1,20 @@
+module GrapeDoc
+  class ApiDocParts
+
+    class Raw < StringBasic
+
+      def initialize(text)
+        super(text)
+      end
+
+      def to_textile
+        "<pre>#{self.to_s}</pre>"
+      end
+
+    end
+
+    class Text < StringBasic
+    end
+
+  end
+end

data/lib/grape/doc/doc_class/sidebar.rb

@@ -0,0 +1,15 @@
+module GrapeDoc
+  class ApiDocParts
+
+    class Sidebar < StringObject
+      def to_textile
+        [
+            '<div style="float:right;">',
+            self.to_s,
+            '</div>'
+        ].join("\n")
+      end
+    end
+
+  end
+end

data/lib/grape/doc/doc_class/table.rb

@@ -0,0 +1,17 @@
+module GrapeDoc
+  class ApiDocParts
+
+    class Table < ArrayObject
+
+      def pust(*args)
+        raise(ArgumentError,'invalid input for table!') if args.any?{|e| !(e.class <= Array) }
+        super(*args)
+      end
+
+      def to_textile
+        self.map{|row| row.join(' | ') }.join("\n")
+      end
+    end
+
+  end
+end

data/lib/grape/doc/doc_class.rb

@@ -0,0 +1,26 @@
+module GrapeDoc
+
+  class ApiDocumentation < Array
+
+    def create(type,*args)
+      raise(ArgumentError,'invalid type') unless [String,Symbol].any?{ |klass| type.class <= klass }
+      return Helpers.constantize("GrapeDoc::ApiDocParts::#{Helpers.camelize(type)}").new(*args)
+    end
+
+    def add(type,*args)
+      self.push(create(type,*args))
+    end
+
+    def br(int=1)
+      raise unless int.class <= Integer
+      int.times{self.push(ApiDocParts::Br.new("\n"))}
+    end
+
+    def to_textile
+      require 'RedCloth'
+      RedCloth.new(self.map{|e| e.to_textile }.join("\n"))
+    end;alias to_s to_textile
+
+  end
+
+end

data/lib/grape/doc/generator.rb

@@ -0,0 +1,127 @@
+module GrapeDoc
+  class Generator
+
+    def initialize(opts={})
+      
+      raise(ArgumentError,'invalid options given') unless opts.class <= Hash
+      opts.merge!(
+          {
+              format: 'html'
+          }.merge(opts)
+      )
+
+      process_head
+      process_table_of_content
+      process_endpoints
+
+    end
+
+    def document
+      @api_doc ||= ApiDocumentation.new
+    end
+
+    def save
+      File.write File.join(Helpers.doc_folder_path,'api_doc.html'),
+                 RedCloth.new(document.to_textile).to_html
+
+    end;alias save! save
+
+    private
+
+    def process_head
+      document.add :h1, "Rest Api Documentation (#{RackTestPoc.root.split(File::Separator)[-1]})"
+    end
+
+    def process_table_of_content
+      #TODO: Table of content here!
+    end
+
+    def process_endpoints
+
+      # Iterates over all subclasses (direct and indirect)
+      Helpers.each_grape_class do |rest_api_model|
+        rest_api_model.routes.each do |route|
+
+          document.add :h2, "#{route.route_method.to_s.upcase}: #{route.route_path}"
+          document.add :h3, 'Request'
+          document.add :h4, 'description'
+          var = case route.route_description
+
+                  when Hash
+                    (route.route_description.find{|k,v| k == 'desc' || k == :desc } || [])[1] || ''
+
+                  when Array
+                    route.route_description
+
+                  else
+                    route.route_description.to_s
+
+                end
+
+          document.add :list,[*var]
+
+          if route.route_params.length > 0
+            document.add :h4, 'params'
+
+            route.route_params.each do |key,value|
+              document.add :list,[
+                  document.create(:text,key.to_s,:bold),
+                  document.create(:list,value.map{ |k,v| "#{k}: #{v}" })
+              ]
+
+            end
+
+          end
+
+          route_path_var = route.route_path.to_s.sub(/\(\.:format\)$/,'')
+          @poc_data ||= Helpers.poc_data
+          if @poc_data && @poc_data.find{|k,v| k =~ /^#{route_path_var}/ }
+            if -> { @poc_data[route_path_var][route.route_method.to_s.upcase] rescue nil }.call
+              poc_opts = @poc_data[route_path_var][route.route_method.to_s.upcase]
+
+              document.add :h3,'Response'
+              # document.add :raw,poc_opts['response'].to_yaml
+              document.add :h4,'body'
+              document.add :raw,poc_opts['response']['raw_body']
+
+              document.add :h5,'options:'
+
+              document.add :list,[
+                  "'status code: #{poc_opts['response']['status']}",
+                  "format: #{poc_opts['response']['format']}"
+              ]
+
+
+              document.add :h4,'example'
+
+              document.add :h5,'curl sample'
+
+              document.add :raw,[
+                  "curl ",
+                  "-X #{route.route_method.to_s.upcase} ",
+                  "\"http://api_url#{route_path_var}?",
+                  "#{poc_opts['request']['query']['raw']}\""
+              ].join
+
+
+
+            end
+
+
+          end
+        end
+      end
+
+    end
+
+  end
+
+  class << self
+
+    def new(*args)
+      Generator.new(*args)
+    end;alias generate new
+
+  end
+
+end

data/lib/grape/doc/helper.rb

@@ -0,0 +1,110 @@
+module GrapeDoc
+  module Helpers
+    class << self
+
+      def each_grape_class
+        ::ObjectSpace.each_object(::Class) do |api_class|
+          next unless -> { api_class < Grape::API rescue false }.call
+          yield(api_class)
+        end if block_given?
+      end
+
+      def doc_folder_path
+        @doc_folder_path ||= -> {
+          doc_folder_path = File.join(RackTestPoc.root,'doc')
+          File.mkdir doc_folder_path unless File.exist?(doc_folder_path)
+          return doc_folder_path
+
+        }.call
+      end
+
+      def poc_file_path
+        return Dir.glob(
+            File.join(RackTestPoc.root,'test','poc','*.{yml,yaml}')
+        ).max_by(&File.method(:ctime))
+      end
+
+      def poc_data
+        require 'yaml'
+        YAML.load(File.read(poc_file_path))
+      rescue;{}
+      end
+
+      # Tries to find a constant with the name specified in the argument string.
+      #
+      #   'Module'.constantize     # => Module
+      #   'Test::Unit'.constantize # => Test::Unit
+      #
+      # The name is assumed to be the one of a top-level constant, no matter
+      # whether it starts with "::" or not. No lexical context is taken into
+      # account:
+      #
+      #   C = 'outside'
+      #   module M
+      #     C = 'inside'
+      #     C               # => 'inside'
+      #     'C'.constantize # => 'outside', same as ::C
+      #   end
+      #
+      # NameError is raised when the name is not in CamelCase or the constant is
+      # unknown.
+      def constantize(camel_cased_word)
+        names = camel_cased_word.split('::')
+
+        # Trigger a builtin NameError exception including the ill-formed constant in the message.
+        Object.const_get(camel_cased_word) if names.empty?
+
+        # Remove the first blank element in case of '::ClassName' notation.
+        names.shift if names.size > 1 && names.first.empty?
+
+        names.inject(Object) do |constant, name|
+          if constant == Object
+            constant.const_get(name)
+          else
+            candidate = constant.const_get(name)
+            next candidate if constant.const_defined?(name, false)
+            next candidate unless Object.const_defined?(name)
+
+            # Go down the ancestors to check it it's owned
+            # directly before we reach Object or the end of ancestors.
+            constant = constant.ancestors.inject do |const, ancestor|
+              break const    if ancestor == Object
+              break ancestor if ancestor.const_defined?(name, false)
+              const
+            end
+
+            # owner is in Object, so raise
+            constant.const_get(name, false)
+          end
+        end
+      end
+
+
+      # By default, +camelize+ converts strings to UpperCamelCase. If the argument
+      # to +camelize+ is set to <tt>:lower</tt> then +camelize+ produces
+      # lowerCamelCase.
+      #
+      # +camelize+ will also convert '/' to '::' which is useful for converting
+      # paths to namespaces.
+      #
+      #   'active_model'.camelize                # => "ActiveModel"
+      #   'active_model'.camelize(:lower)        # => "activeModel"
+      #   'active_model/errors'.camelize         # => "ActiveModel::Errors"
+      #   'active_model/errors'.camelize(:lower) # => "activeModel::Errors"
+      #
+      # As a rule of thumb you can think of +camelize+ as the inverse of
+      # +underscore+, though there are cases where that does not hold:
+      #
+      #   'SSLError'.underscore.camelize # => "SslError"
+      def camelize(term)
+        string = term.to_s
+        string.capitalize!
+        string.gsub!(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{$2.capitalize}" }
+        string.gsub!('/', '::')
+        string
+
+      end
+
+    end
+  end
+end

data/lib/grape/doc/prototype.rb

@@ -0,0 +1,91 @@
+module GrapeDoc
+  class ApiDocParts
+
+    class StringBasic < String
+
+      class << self
+        def markdown=(obj)
+          @markdown=obj
+        end
+        def markdown
+          @markdown || self.to_s.split('::')[-1].downcase
+        end
+      end
+
+      def initialize(*args)
+        args[0] = Parser.parse(args[0])
+        self.replace(args[0])
+      end
+
+      def markdown
+        self.class.markdown
+      end
+
+      alias to_textile to_s
+
+    end
+
+    class StringObject < StringBasic
+
+      def to_textile
+        "#{markdown}. #{self.to_s}\n"
+      end
+
+    end
+
+    class StringObjectEnded < StringObject
+
+      def to_textile
+        "#{markdown}#{self}#{markdown}\n"
+      end
+
+    end
+
+    class ArrayObject < Array
+
+      class << self
+        def markdown=(obj)
+          @markdown=obj
+        end
+        def markdown
+          @markdown || self.to_s.downcase
+        end
+      end
+
+      def initialize(object)
+        object = Parser.parse(object)
+        self.replace(object)
+      end
+
+      def markdown
+        self.class.markdown
+      end
+
+      def to_textile
+        self.map{|e|
+          case e
+
+            when ArrayObject
+              e.map{|e|
+
+                text = if e.respond_to?(:to_textile)
+                         e.to_textile
+                       else
+                         e.to_s
+                       end
+
+                "#{markdown}#{markdown} #{text}"
+
+              }.join("\n")
+
+            else
+              "#{markdown} #{e}"
+
+          end
+        }.push('').join("\n")
+      end
+
+    end
+
+  end
+end

data/lib/grape-doc.rb

@@ -1 +1,2 @@
-require 'grape/doc/logic'
+require 'loader'
+require_relative_directory_r 'grape/doc'

data/test/sample.html

@@ -0,0 +1,16 @@
+<h1>Rest Api Documentation (grape-doc)</h1>
+<h2><span class="caps">GET</span>: /hello(.:format)</h2>
+<h3>Request</h3>
+<h4>description</h4>
+<ul>
+	<li>Hello world!</li>
+</ul>
+<h4>params</h4>
+<ul>
+	<li>test
+	<ul>
+		<li>required: false</li>
+		<li>type: String</li>
+		<li>desc: it&#8217;s a test string</li>
+	</ul></li>
+</ul>

data/test/test_doc_gen.rb

@@ -0,0 +1,13 @@
+require_relative 'test_helper'
+describe 'Doc generating' do
+
+  specify 'test documentation generator' do
+
+    var = GrapeDoc.new
+    puts var.document.to_textile
+    File.write File.join(RackTestPoc.root,'test','sample.html'),
+               var.document.to_textile.to_html
+
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,33 @@
+require 'grape'
+require 'rack/test'
+require 'rack/test/poc'
+
+require 'grape-doc'
+
+require 'minitest/autorun'
+
+class TestAPI1 < Grape::API
+
+  version 'v1', using: :accept_version_header
+
+  default_format :txt
+  format :json
+
+  content_type :txt,  'application/text'
+  content_type :json, 'application/json'
+
+  desc 'Hello world!'
+  params do
+    optional :test,
+             type: String,
+             desc: 'it\'s a test string'
+
+  end
+  get 'hello' do
+    {hello: "world!"}
+  end
+
+end
+
+class TestAPI2 < TestAPI1
+end

data/test/test_object_space_collector.rb

@@ -0,0 +1,23 @@
+require_relative 'test_helper'
+describe 'Object Space Collector' do
+
+  specify 'test that there will be api classes on calling each_grape_class' do
+    GrapeDoc::Helpers.each_grape_class do |api_class|
+      api_class.must_be_instance_of Class
+      (api_class < Grape::API).must_be :==, true
+
+      api_class.respond_to?(:routes).must_be :==, true
+      api_class.routes.respond_to?(:each).must_be :==, true
+
+      api_class.routes.each do |r|
+        r.route_method.must_be_instance_of String
+        r.route_path.must_be_instance_of String
+        r.route_params.must_be_instance_of Hash
+
+      end
+
+    end
+
+  end
+
+end