amy 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 84014c35977967c74c5d0cd3dc3f979ab252591e
+  data.tar.gz: 891c47801a0a669786da8792f57d9d5a46ea778f
+SHA512:
+  metadata.gz: 5cec160b99dde0d735405afde3a379729cd153237afcee2dfa8e813e3ff00c3e0222ad472cda3cfb3a6a57efd5806570ea478a3f041deb498c978756fdeecf3e
+  data.tar.gz: d14dc381267e319f47cc016ba76b6936a7fa6ff6b0eec257b139c0c55334aa7c2a557f6f9c36070f2c8d1161e379206e60e1cef7709e0e093154e016a4b20bc6

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Pere Urbon-Bayes
+
+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.markdown

@@ -0,0 +1,50 @@
+# Amy
+
+![image](http://rachstick.files.wordpress.com/2012/04/amy-f.jpg)
+
+Amy aims to be a documentation engine, something alike rdoc, but for REST APIs. With the motivation in mind to solve this situation, that has not much of options, specially in the ruby world.
+
+With two mode of work, Amy can:
+
+* Scrap a list of documentation files.
+* Scrap your source code looking for special comments. ``Currently just works for sinatra``
+
+and use this info to compose a nice website with your API docs.
+
+At the documentation website you will be able to see the resources aggregated per each url pattern, and within them see each method, in a very REST way. In some cases, for the GET, HEAD and OPTIONS methods you will be able to run them and analise the output.
+
+## I want to use it!
+
+First of all, you've to understand this is in very pre alpha status, so everything can change in the near feature. But if you are still a brave man, you can take a look at [examples](examples) directory to see who to run this gem.
+
+If you've a nice feature in mind, please submit a pull request, every contribution is wellcome.
+
+To create the documentation website you've to run:
+
+* ` amy [directory with the definitions] `
+
+There is an option to create a ``.amy`` file in your main directory where you'll be able to tune a few options for the engine. Take a look at [.amy](.amy) for an example.
+
+## TODO:
+
+Next, and preatty obvious thing, is to write a decent documentation.
+I've in mind also to extend the source code parsing capabilities to include:
+* A better content management skills.
+* Support for more web frameworks and programming languages.
+
+and I'm sure many others will popup.
+
+## Contributing to Amy
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2014 Pere Urbon-Bayes. See LICENSE.txt for further details.
+

data/bin/amy

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require 'amy'
+
+if (ARGV.size != 1)
+  puts "USAGE: amy.rb [dir]"
+  exit(0)
+end
+
+parser = Amy::Parser.new
+parser.execute ARGV[0]
+exit(1)

data/lib/amy/generate.rb

@@ -0,0 +1,23 @@
+require 'erb'
+require 'amy/templates/main'
+
+module Amy
+  class Generator
+
+    attr_reader :base_dir
+
+    def initialize(base_dir="doc/")
+      @base_dir = base_dir
+    end
+
+    def do(template, object)
+      Dir.mkdir(@base_dir) if (not File.exist?(@base_dir) or not File.directory?( @base_dir ))
+      ehtml  = ERB.new(IO.read(template))
+      output = ehtml.result(object.get_binding)
+      File.open("#{@base_dir}#{object.path}", 'w') do |f|
+        f.write(output)
+      end
+    end
+
+  end
+end

data/lib/amy/parser/defs.rb

@@ -0,0 +1,25 @@
+module Parser
+  class Defs
+
+    attr_accessor :method, :url
+
+    def initialize
+      @props  = {}
+      @method = ""
+      @url    = ""
+    end
+
+    def add_prop(key, text)
+      @props[key] = text
+    end
+
+    def get_props
+      @props
+    end
+
+    def empty?
+      @props.empty?
+    end
+
+  end
+end

data/lib/amy/parser/lexer.rb

@@ -0,0 +1,118 @@
+require 'amy/parser/tokens'
+
+module Parser
+  class Lexer
+
+    def initialize
+      @filename = ""
+      @file     = nil
+      @debug    = false
+    end
+
+    def set_debug(debug)
+      @debug = debug
+    end
+
+    def set_input(file)
+      @filename = file
+      @file     = File.new(file)
+    end
+
+    ##
+    # Get's the next token
+    #
+    def next
+      raise IOError.new("Stream is at the end of file.") if eof?
+      end_of_token = false
+      token = ""
+      while not end_of_token
+        c = @file.getc
+        puts "next c: #{c.inspect} v: #{valid_char?(c)} s: #{single_char?(c)} e: #{is_end_character?(c)}" if @debug
+        if eof? then
+          end_of_token = true
+        elsif (single_char?(c)) then
+          if (token.empty?) then
+              token = c
+              next_token = @file.getc
+              if ('#' == token and '#' == next_token) then
+                token << next_token
+              else
+                @file.seek(-1, IO::SEEK_CUR)
+              end
+          else
+            @file.seek(-1, IO::SEEK_CUR)
+          end
+          end_of_token = true
+        elsif (valid_char?(c)) then
+          token << c
+        elsif is_end_character?(c) then
+          move_till_next_token
+          end_of_token = (not token.empty?)
+        end
+      end
+      puts "next" if @debug
+      build_token(token)
+    end
+
+    ##
+    # Set's the lexer back to the begin
+    #
+    def rewind
+      @file.rewind
+    end
+
+    def eof?
+      @file.eof?
+    end
+
+    def lineno
+      @file.lineno
+    end
+
+    private
+
+    def move_till_next_token
+      there = false
+      while not there
+        c = @file.getc
+        puts "move c:#{c.inspect} v: #{valid_char?(c)} s: #{single_char?(c)}" if @debug
+        if eof? then
+          there = true
+        elsif single_char?(c) or valid_char?(c) then
+          @file.seek(-1, IO::SEEK_CUR)
+          there = true
+        end
+      end
+      puts "move" if @debug
+    end
+
+    def valid_char?(c)
+      not (c =~ /[[:alpha:]|[:digit:]|_|@|<|:|-]/).nil?
+    end
+
+    def single_char?(c)
+      not (c =~ /['|"|#|\/|\\|\[|\]|\.|\n]/).nil?
+
+    end
+
+    def is_white_space?(c)
+      not (c =~ /\s/).nil?
+    end
+
+    def is_end_character?(c)
+      eof? or single_char?(c) or !valid_char?(c)
+    end
+
+    def build_token(token)
+      type = Tokens::STRING
+      if (token.start_with?("##"))
+        type = Tokens::COMMENT_TAG
+      elsif (token.start_with?("#"))
+        type = Tokens::COMMENT
+      elsif (token.start_with?("@")) 
+        type = Tokens::PROPERTY
+      end
+      Token.new(type, token, @file.lineno)
+    end
+  end
+end

data/lib/amy/parser/parser.rb

@@ -0,0 +1,91 @@
+require 'amy/parser/lexer'
+require 'amy/parser/defs'
+
+module Parser
+  class Parser
+    
+    def initialize
+       @lexer = Lexer.new
+    end
+
+    def parse(file)
+      @lexer.set_input(file)
+      parse_tokens(@lexer)
+    end
+
+    private
+
+    def parse_tokens(lexer)
+      defs = []
+      while(not lexer.eof?)
+        token = lexer.next
+        if token.is_ct? then
+          _def = parse_defs(lexer)
+          defs << _def unless _def.empty?
+        end
+      end
+      return defs
+    end
+
+    def parse_defs(lexer)
+      defs = Defs.new
+      return defs if (lexer.eof?)
+      finish = false
+      prop   = ""
+      value  = ""
+      mode   = :normal
+      while (not lexer.eof? and not finish)
+        token = lexer.next
+        if :normal == mode and token.is_ct? then
+          set_property defs, prop, value
+          finish = true
+        elsif :content == mode and token.is_p? and "@end" == token.value then
+          mode = :normal
+          set_property defs, prop, value
+        elsif prop.empty? and token.is_p? then
+          prop = token.value
+          mode = :content if "@content" == prop
+        elsif not prop.empty? and token.is_p? then
+          set_property defs, prop, value
+          prop = token.value
+          value = ""
+          mode = :content if "@content" == prop
+        elsif not prop.empty? and token.is_s? then
+          value << " #{token.value}"
+        end
+      end
+      lexer.next
+      defs.method = lexer.next.value
+      finish = false
+      lexer.next
+      while(not lexer.eof? and not finish)
+        token = lexer.next
+        if ["'", '"'].include?(token.value) then
+          finish = true
+        else
+          defs.url << token.value
+        end
+      end
+      return defs
+    end
+
+    def set_property(defs, prop, value)
+      if ("@params" == prop) then
+        params = {}
+        fields = value.split(" ")
+        last_key = ""
+        fields.each_with_index do |field, i|
+          if (i%2 == 0) then
+            last_key = field
+          else
+            params[last_key] = field
+            last_key = ""
+          end
+        end
+        defs.add_prop prop, params
+      else
+        defs.add_prop prop, value.strip
+      end
+    end
+  end
+end

data/lib/amy/parser/tokens.rb

@@ -0,0 +1,39 @@
+module Parser
+  
+  module Tokens
+    STRING      = 'string'
+    COMMENT_TAG = 'comment_tag'
+    COMMENT     = 'comment'
+    PROPERTY    = 'property'
+    TEXT        = 'text'
+  end
+
+  class Token
+    attr_accessor :type, :value, :lineno
+    def initialize(type, value, lineno)
+      @type   = type
+      @value  = value
+      @lineno = lineno
+    end
+
+    def is_ct?
+      Tokens::COMMENT_TAG == @type
+    end
+    def is_c?
+      Tokens::COMMENT == @type or Tokens::COMMENT_TAG == @type
+    end
+
+    def is_p?
+      Tokens::PROPERTY == @type
+    end
+
+    def is_s?
+      Tokens::STRING == @type
+    end
+
+    def is_a?(type)
+      @type == type
+    end
+
+  end
+end

data/lib/amy/parser.rb

@@ -0,0 +1,129 @@
+require 'fileutils'
+require 'maruku'
+require 'amy/parser/parser'
+
+module Amy
+  class Parser
+
+    OPTIONS_FILE = ".amy"
+
+    def initialize(base_dir = "doc/")
+      @generator = Amy::Generator.new base_dir
+      @options   = load_options_file
+      @mode      = @options['mode'] || 'file'
+    end
+
+    require 'pp'
+
+    def execute(dir)
+      specs  = load_specs dir
+      if (@mode == "code")
+        specs['links'] = @options['links']
+        specs['base_url'] = @options['base_url']
+        specs['api_version'] = @options['api_version']
+      end
+      compile_json_specs_with dir, specs
+      generate_main_page_with specs
+      copy_styles_and_js
+      true
+    end
+
+    private
+
+    def compile_json_specs_with(dir, specs)
+      specs['resources'].each_pair { |resource, options|
+         resource_spec = JSON.parse(IO.read(File.join(File.join(dir, options['dir']),"resource.def")))
+         options['config'] = build_resource File.join(dir, options['dir']), resource_spec
+      } if (@mode == "file")
+      File.open("#{Amy::BASE_DIR}/views/js/data.json", 'w') do |f|
+        f.write(specs.to_json)
+      end
+    end
+
+    def build_resource(dir, specs)
+     resources = Dir.new(dir)
+     to_skip   = [ '.', '..', 'resource.def' ]
+     record    = specs['config']
+     resources.entries.each do |entry|
+        next if to_skip.include?(entry)
+        content = IO.read File.join(resources.path, entry)
+        method  = File.basename(entry, File.extname(entry)).upcase
+        doc     = Maruku.new(content)
+        record[method.downcase]['content'] = doc.to_html
+     end
+     record
+    end
+
+    def generate_main_page_with(specs)
+      main_page = Amy::Model::Main.new
+      specs['resources'].each_pair { |resource, options|
+         main_page.add_resource( { 'resource' => resource, 'title' => options['title'] } )
+      }
+      main_page.set_links    specs['links'] || []
+      main_page.set_version  specs['api_version']
+      main_page.set_base_url specs['base_url']
+      @generator.do("#{Amy::BASE_DIR}/views/main.erb.html", main_page)
+    end
+
+    def load_specs(dir)
+      if "file" == @mode then
+        JSON.parse(IO.read(File.join(dir,"/specs.def")))
+      elsif "code" == @mode then
+        { 'resources' => parse_source_code(dir) }
+      end
+    end
+
+    def parse_source_code(dir)
+      parser = ::Parser::Parser.new
+      data   = {}
+      Dir.foreach(dir) do |file|
+        next if [".", ".."].include?(file)
+        path = File.join(dir, file)
+        if (File.directory?(path)) then
+          parse_source_code(path).each_pair do |key, val|
+            if data[key].nil? then
+               data[key] = val
+            else
+              data[key].merge!(val)
+            end
+          end
+        else
+          defs = parser.parse(path)
+          if not defs.empty? then
+            defs.each do |_def|
+              data[_def.url] = { 'title' => '', 'config' => {} } if data[_def.url].nil?
+              record = { 'url' => _def.url, 'title' => _def.get_props["@title"], 'content' => '' }
+              if _def.get_props['@params'] then
+                record['params'] = []
+                _def.get_props['@params'].each_pair do |k,v|
+                  record['params'] << [k,v]
+                end
+              end
+              record['content'] = _def.get_props['@content'].gsub(/\n/,'<br/>') if _def.get_props['@content']
+              if _def.get_props['@description'] then
+                data[_def.url]['title'] = _def.get_props['@description']
+              end
+              data[_def.url]['config'][_def.method] = record
+            end
+          end
+        end
+      end
+      return data
+    end
+
+    def copy_styles_and_js
+      base_dir = @generator.base_dir
+      Dir.mkdir("#{base_dir}/js")
+      FileUtils.cp("#{Amy::BASE_DIR}/views/js/amy.min.js", "#{base_dir}/js/amy.js")
+      FileUtils.cp("#{Amy::BASE_DIR}/views/js/data.json", "#{base_dir}/data.json")      
+      Dir.mkdir("#{base_dir}/style")
+      FileUtils.cp("#{Amy::BASE_DIR}/views/style/style.css", "#{base_dir}/style/style.css")
+    end
+
+    def load_options_file
+      return {} unless File.exist?(OPTIONS_FILE)
+      YAML::load(File.open(OPTIONS_FILE))
+    end
+
+  end
+end

data/lib/amy/templates/main.rb

@@ -0,0 +1,36 @@
+module Amy::Model
+  
+  class Main
+
+    attr_reader :path
+
+    def initialize
+      @resources  = []
+      @apiversion = ""
+      @base_url   = ""
+      @links      = []
+      @path       = 'index.html'
+    end
+
+    def add_resource(resource)
+      @resources << resource
+    end
+   
+    def set_links(links=[])
+      @links = links
+    end
+
+    def set_version(version)
+      @apiversion = version
+    end
+
+    def set_base_url(base_url)
+      @base_url = base_url
+    end
+
+    def get_binding
+      binding
+    end
+
+  end
+end

data/lib/amy.rb

@@ -0,0 +1,8 @@
+require 'json'
+require 'yaml'
+require 'amy/parser'
+require 'amy/generate'
+
+module Amy
+  BASE_DIR = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+end

data/views/js/amy.coffee

@@ -0,0 +1,79 @@
+class Tabelle
+
+  constructor: ->
+    return
+
+  setup: (url) ->
+   self = this
+   request_config =
+       url: url+"?date="+(new Date()).getTime()
+       type: "GET"
+       dataType: "json"
+       success: (data) ->
+          $('.resources div').remove()
+          i = 0
+          for resource,config of data['resources']
+            resource = self.add_resource(resource, config, i, data['base_url'])
+            resource.toggle()
+            i++
+          self.add_resource_events(data)
+          self.toggle_method_if_necessary()
+       error: (e) ->
+          $('.resources div').remove()
+   $.ajax request_config
+   return
+
+  add_resource: (name, resource, i, base_url="") ->
+      resource = new Resource(name, resource, i, base_url)
+      resource.build()
+      return resource
+
+  add_resource_events: (data) ->
+      handlerIn = () ->
+        $(this).css("background", "#f5f5f5")
+        $(this).children('div').children().css('color', 'black')
+        return
+      handlerOut = () ->
+        $(this).css("background", "#fff")
+        $(this).children('div').children().css('color', '#999')
+        return
+      $(".resource").hover(handlerIn, handlerOut)
+      $('.resource').click ->
+        event.stopPropagation()
+        $(this).next().fadeToggle()
+        return
+      return
+
+  toggle_method_if_necessary: -> 
+      anchor = window.location.hash.replace('!','')
+      anchor = anchor.replace(/\//g,"\\/")
+      anchor = anchor.replace(/:/g,'\\:')
+      fields = anchor.split('#')
+      $("#"+fields[1]+" + div .method."+fields[2]+" .content").fadeToggle()
+      $("#"+fields[1]+" + div .method."+fields[2]+" .form").fadeToggle()
+      $("#"+fields[1]).next().fadeToggle()
+      return
+
+  @toggleMethods: (i) ->
+      event.stopPropagation()
+      $("#resource#{i}").fadeToggle()
+      return
+  @showJSON: ->
+      event.stopPropagation()
+      url = $("#selector #key").val()
+      window.open(url, "_self") if url
+      return
+
+  window.toggleMethods = Tabelle.toggleMethods
+  window.showJSON      = Tabelle.showJSON
+
+$(document).ready ->
+ tabelle = new Tabelle
+ utils   = new Utils
+ utils.toggle_by_class 'content'
+ url = utils.default_config_url()
+ $('#header #selector input').val(url)
+ tabelle.setup(url)
+ $('#header #explore').click ->
+   tabelle.setup($('#header #selector input').val())
+ return