calamum 1.0.0

data/.gitignore

@@ -0,0 +1,18 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+tmp
+pkg

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in turntable.gemspec
+gemspec
+

data/Gemfile.lock

@@ -0,0 +1,44 @@
+PATH
+  remote: .
+  specs:
+    calamum (1.0.0)
+      activemodel
+      mixlib-cli
+      mixlib-config
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (3.0.17)
+      activesupport (= 3.0.17)
+      builder (~> 2.1.2)
+      i18n (~> 0.5.0)
+    activesupport (3.0.17)
+    builder (2.1.2)
+    coderay (1.0.8)
+    diff-lcs (1.1.3)
+    i18n (0.5.0)
+    method_source (0.8.1)
+    mixlib-cli (1.3.0)
+    mixlib-config (1.1.2)
+    pry (0.9.12)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rspec (2.12.0)
+      rspec-core (~> 2.12.0)
+      rspec-expectations (~> 2.12.0)
+      rspec-mocks (~> 2.12.0)
+    rspec-core (2.12.2)
+    rspec-expectations (2.12.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.12.1)
+    slop (3.4.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  calamum!
+  pry
+  rspec

data/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright (C) <year> <copyright holders>
+
+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.md

@@ -0,0 +1,35 @@
+Calamum 
+=============
+
+Calamum is a simple ruby build program to generate a REST API documentation from a YAML file definition.
+
+## Installation
+
+
+### Gem Installation
+
+Download and install rake with the following.
+
+    $gem install calamum
+
+## Usage
+
+     calamum -h
+     Usage: /bin/calamum (options)
+       -d, --debug                      Show actions to do (default)
+       -f, --file DEFINITION            Definition YAML file (required)
+       -p, --path PATH                  The distination path for the generated doc directory
+       -t, --template TEMPLATE          Documentation HTML template
+       -v, --version                    Show calamum version
+       -h, --help                       Show this message
+### Simple Example
+First, you must write a YAML file which contains the definition of your REST API.
+A simple example file 'sample.yml' in sample directory.
+
+Next just run the calamum command as following:
+     
+     $calamum -f my_api_definition.yml
+
+A "doc" directory is generated (by default in your home path, to change it specify the option '-p/--path') with a index file that contain your API Documentation.
+
+Open the index.html file in your browser to show your api doc. 

data/bin/calamum

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+#
+# Author:: Mehrez Alachheb (<lachheb.mehrez@gmail.com>)
+
+$: << File.join(File.dirname(__FILE__), "..", "lib")
+
+require 'rubygems'
+require 'calamum/runner'
+
+Calamum::Runner.new.run

data/calamum.gemspec

@@ -0,0 +1,25 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'calamum/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "calamum"
+  gem.version       = Calamum::VERSION
+  gem.authors       = ["Mehrez Alachheb"]
+  gem.email         = ["lachheb.mehrez@gmail.com"]
+  gem.description   = %q{Calamum is a simple ruby build program to generate a REST API documentation from a YAML file definition}
+  gem.summary       = %q{Calamum is a simple ruby build program to generate a REST API documentation from a YAML file definition}
+  gem.homepage      = "https://github.com/malachheb/liblvm"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+  gem.bindir            = "bin"
+
+  gem.add_dependency 'activemodel'
+  gem.add_dependency 'mixlib-cli'
+  gem.add_dependency 'mixlib-config'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'pry'
+end

data/lib/calamum/calamum_helper.rb

@@ -0,0 +1,10 @@
+
+
+def puts_info(msg)
+  $stdout.puts "\e[32m[INFO] #{msg}\e[0m" if Calamum::Config[:debug]
+end
+
+def puts_error(msg)
+  $stderr.puts "\e[31m[ERROR] #{msg}\e[0m" if Calamum::Config[:debug]
+  exit(1)
+end

data/lib/calamum/config.rb

@@ -0,0 +1,13 @@
+require 'calamum'
+require 'mixlib/config'
+
+module Calamum
+  class Config
+    extend Mixlib::Config
+
+    def self.inspect
+      configuration.inspect
+    end
+
+  end 
+end

data/lib/calamum/definition_parser.rb

@@ -0,0 +1,71 @@
+
+class Calamum::DefinitionParser
+  attr_accessor :definition, :resources
+
+  def initialize(definition_yaml)
+    @definition = definition_yaml
+    @resources = Hash.new
+  end
+
+  def get_resources
+    @definition['resources']
+  end
+
+  def get_name
+    @definition['name']
+  end
+
+  def get_url
+    @definition['url']
+  end
+
+  def get_resources_names
+    @definition['resources'].inject([]){|resources, (key, content)| resources << key}
+  end
+
+  def load_requests
+    self.get_resources.each do |resource, requests|
+      @resources[resource] = []
+      index = 0
+      requests.each do |request|
+        req = initialize_request(request)
+        unless req.nil?
+          @resources[resource][index]= req
+          index += 1
+        end
+      end
+    end
+    @resources
+  end
+
+  def initialize_request(request)
+    req = Calamum::Request.new({
+                                 :uri =>  request['uri'],
+                                 :action => request['action'],
+                                 :params => request['params'],
+                                 :description => request['description'],
+                                 :headers => request['headers'],
+                                 :response => request['response'],
+                               })
+    if req.errors.empty?
+      puts_info "Request #{request['action']}: #{request['uri']} loading success"
+      req
+    else
+      puts_error "Request #{request['action']}: #{request['uri']} not valid: #{req.errors}"
+      nil
+    end
+  end
+
+  def get_resource_uris(name)
+    @resources[name]
+  end
+
+  def find_resource_uri_by_label(resource, label)
+    @resources.select{|r| r['label']==label}.first['uri']
+  end
+
+  def find_resource_action_by_label(resource, label)
+    @resources.select{|r| r['label']==label}.first['action']
+  end
+
+end

data/lib/calamum/doc_generator.rb

@@ -0,0 +1,61 @@
+
+class Calamum::DocGenerator
+  include ERB::Util
+  attr_accessor :resources, :templaete, :name, :url
+
+  def initialize(template, resources, name, url)
+    @template = template
+    @resources = resources
+    @name = name
+    @url = url
+  end
+
+  def render()
+    ERB.new(@template).result(binding)
+  end
+
+  def self.load_template
+    File.read(File.join(File.dirname(__FILE__), "templates", "bootstrap", "index.html.erb"))
+  end
+  
+  def save_result(file)
+    initialize_doc_dir
+    File.open(file, "w+") do |f|
+      f.write(render)
+    end
+  end
+
+  def initialize_doc_dir
+    create_doc_dir
+    Dir.mkdir File.join(Calamum::Config[:path], 'doc', 'assets')
+    copy_assets
+  end
+
+  def copy_assets
+    src = File.join(File.dirname(__FILE__), "templates", Calamum::Config[:template], "assets")
+    dst = File.join(Calamum::Config[:path], 'doc', 'assets')
+    begin
+      FileUtils.copy_entry(src, dst)
+    rescue => e
+      puts_error e.message
+    end
+  end
+
+  def create_doc_dir
+    doc_dir = File.join(Calamum::Config[:path], 'doc')
+    if File.exist?(doc_dir)
+      while true
+        print "The filename directoy #{doc_dir} already exists. Do you want to overwrite it? [Y/N]: "
+        case $stdin.gets.chomp!.downcase
+        when 'y'
+          FileUtils.rm_r(doc_dir, :force => true)
+          break
+        when 'n'
+         exit(1) 
+        end
+      end
+    end
+    Dir.mkdir doc_dir
+  end
+
+end

data/lib/calamum/request.rb

@@ -0,0 +1,40 @@
+class Calamum::Request
+  include ActiveModel::Validations
+
+  attr_reader :errors
+  attr_accessor :uri, :action, :params, :description, :headers, :response
+  ACTIONS= %{GET POST PUT DELETE}
+
+  validates :uri, :action, :presence => true
+  # validates :uri, :uniqueness => true
+  validates :action, :inclusion => { :in => ACTIONS, :message => "is not included in [#{ACTIONS}]"}
+
+  def initialize(attrs)
+    @uri= attrs[:uri]
+    @action= attrs[:action].upcase
+    @params= attrs[:params] || {}
+    @headers = attrs[:headers] || {}
+    @response = attrs[:response] || ''
+    @description = attrs[:description]
+    @errors = ActiveModel::Errors.new(self)
+    self.valid?
+  end
+
+  def action_label
+    case @action
+    when 'GET'
+      'label-info'
+    when 'POST'
+      'label-success'
+    when 'PUT'
+      'label-warning'
+    when 'DELETE'
+      'label-important'
+    end
+  end
+
+  def to_s
+    "#{action}: #{uri}"
+  end
+
+end

data/lib/calamum/runner.rb

@@ -0,0 +1,84 @@
+require 'calamum'
+require 'calamum/config'
+require 'calamum/doc_generator'
+require 'mixlib/cli'
+
+class Calamum::Runner
+  include Mixlib::CLI
+  CMD_NAME = "calamum"
+
+  def initialize
+    super
+  end
+
+  option :help,
+    :short        => "-h",
+    :long         => "--help",
+    :description  => "Show this message",
+    :on           => :tail,
+    :boolean      => true,
+    :show_options => true,
+    :exit         => 0
+
+  option :version,
+    :short        => "-v",
+    :long         => "--version",
+    :description  => "Show #{CMD_NAME} version",
+    :boolean      => true,
+    :proc         => lambda {|v| puts "Calamum: #{Calamum::VERSION}"},
+    :exit         => 0
+
+  option :debug,
+    :short        => "-d",
+    :long         => "--debug",
+    :description  => "Show actions to do (default)",
+    :boolean      => true,
+    :default      => true,
+    :proc         => lambda { |p| true }
+
+  option :definition,
+    :short        => "-f DEFINITION",
+    :long         => "--file DEFINITION",
+    :description  => "Definition YAML file",
+    :required => true
+
+  option :template,
+    :short        => "-t TEMPLATE",
+    :long         => "--template TEMPLATE",
+    :description  => "Documentation HTML template",
+    :default      =>  "bootstrap"
+
+  option :path,
+    :short        => "-p PATH",
+    :long         => "--path PATH",
+    :description  => "The distination path for the generated doc directory",
+    :default      =>  ENV['HOME']
+
+  def run
+    load_options
+    Calamum::Config.merge!(config)
+    api_definition = load_definition_file
+    @definition = Calamum::DefinitionParser.new(api_definition)
+    @definition.load_requests
+    template = Calamum::DocGenerator.load_template
+    html_output = Calamum::DocGenerator.new(template, @definition.resources, @definition.get_name, @definition.get_url)
+    html_output.save_result(File.join(Calamum::Config[:path], 'doc', 'index.html'))
+  end
+
+  def load_definition_file
+    begin
+       YAML.load(File.open(config[:definition]))
+    rescue => e
+      puts_error e.message
+    end
+  end
+
+  def load_options
+    begin
+      parse_options
+    rescue => e
+      puts_error e.message
+    end
+  end
+
+end