calamum 1.0.2 → 1.1.0

data/bin/calamum

@@ -1,8 +1,8 @@
 #!/usr/bin/env ruby
 #
-# Author:: Mehrez Alachheb (<lachheb.mehrez@gmail.com>)
-
-$: << File.join(File.dirname(__FILE__), "..", "lib")
+# Calamum is a simple REST API documentation generator.
+# This is a fork, that allows you to work with JSON format.
+$: << File.join(File.dirname(__FILE__), '..', 'lib')
 
 require 'rubygems'
 require 'calamum/runner'

data/lib/calamum.rb

@@ -1,9 +1,15 @@
+require 'erb'
+require 'yajl'
 require 'yaml'
+require 'fileutils'
 require 'pry'
-require 'erb'
-require 'active_model'
-require 'calamum/calamum_helper'
-require "calamum/version"
-require "calamum/config"
-require "calamum/definition_parser"
-require "calamum/request"
+
+module Calamum
+  require 'calamum/config'
+  require 'calamum/helpers'
+  require 'calamum/resource'
+  require 'calamum/doc_parser'
+  require 'calamum/doc_generator'
+  require 'calamum/version'
+  VALID_TEMPLATES = %{twitter bootstrap}
+end

data/lib/calamum/config.rb

@@ -1,13 +1,21 @@
 require 'calamum'
 require 'mixlib/config'
 
-module Calamum
-  class Config
-    extend Mixlib::Config
+# Provides a class-based configuration object.
+# See https://github.com/opscode/mixlib-config
+class Calamum::Config
+  extend Mixlib::Config
 
-    def self.inspect
-      configuration.inspect
-    end
+  def self.inspect
+    configuration.inspect
+  end
+
+  def self.apply(config)
+    merge!(config)
+
+    self.doc_path = File.join(config[:path], 'docs')
+    self.tpl_path = File.join(File.dirname(__FILE__), 'templates', config[:template])
+    raise "Unknown template #{config[:template]}" unless Calamum::VALID_TEMPLATES.include?(config[:template])
+  end
 
-  end 
 end

data/lib/calamum/doc_generator.rb

@@ -1,62 +1,33 @@
-
 class Calamum::DocGenerator
-  include ERB::Util
-  attr_accessor :resources, :template, :name, :url, :description
+  attr_accessor :template
 
-  def initialize(template, resources, name, url, descr)
-    @template = template
-    @resources = resources
-    @name = name
-    @url = url
-    @description = descr
-  end
+  def initialize(tpl_name)
+    tpl_path = Calamum::Config[:tpl_path]
+    filename = "#{tpl_path}/#{tpl_name}.html.erb"
 
-  def render()
-    ERB.new(@template).result(binding)
+    @template = ERB.new(File.read(filename))
   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 self.init_base_dir
+    tpl_path = Calamum::Config[:tpl_path]
+    doc_path = Calamum::Config[:doc_path]
+    FileUtils.rm_r(doc_path, :force => true)
+    Dir.mkdir(doc_path)
 
-  def initialize_doc_dir
-    create_doc_dir
-    Dir.mkdir File.join(Calamum::Config[:path], 'doc', 'assets')
-    copy_assets
+    # copy assets from template directory
+    source = File.join(tpl_path, 'assets')
+    target = File.join(doc_path, 'assets')
+    FileUtils.copy_entry(source, target)
   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
+  def save_template(filename, values)
+    values.each do |k, v|
+      instance_variable_set("@#{k}", v)
     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
+    html_data = @template.result(binding)
+    filename = File.join(Calamum::Config[:doc_path], filename)
+    File.open(filename, 'w+') { |file| file.write(html_data) }
   end
 
 end

data/lib/calamum/doc_parser.rb

@@ -0,0 +1,49 @@
+class Calamum::DocParser
+  attr_accessor :resources, :definition
+
+  def initialize(definition)
+    @resources = Hash.new
+    @definition = definition
+  end
+
+  def get_url
+    @definition['url']
+  end
+
+  def get_name
+    @definition['name']
+  end
+  
+  def get_version
+    @definition['version']
+  end
+  
+  def get_description
+    @definition['description']
+  end
+
+  def get_resources
+    Calamum::Config[:sort]? @definition['resources'].sort : @definition['resources']
+  end
+
+  def load_resources
+    get_resources.each do |name, methods|
+      list = []
+      methods.each do |resource|
+        if validate_resource?(resource)
+          list << Calamum::Resource.new(resource)
+          puts_info "#{resource['action']}: #{resource['uri']}"
+        else
+          puts_warning "Resource #{resource['action']}: #{resource['uri']} has incorrect definition"
+        end
+      end
+      @resources[name] = list if list.any?
+    end
+    @resources
+  end
+
+  def validate_resource?(resource)
+    resource['uri'] && resource['action'] && resource['description'] && %{GET POST PUT DELETE}.include?(resource['action'].upcase)
+  end
+
+end

data/lib/calamum/helpers.rb

@@ -0,0 +1,31 @@
+# Returns a formatted JSON string.
+#
+# @param json [String] JSON string to format
+# @param indent [String] indent that used in formatting
+# @return [String] prettier form of the given JSON string
+def pj(json, indent = ' ')
+  require 'json'
+  JSON.pretty_generate(json, :indent => indent * 4).gsub!(/\n/, '<br/>')
+end
+
+# Output info message to console.
+#
+# @param msg [String] message to output
+def puts_info(msg)
+  $stdout.puts "\e[32m[INFO] #{msg}\e[0m" if Calamum::Config[:debug]
+end
+
+# Output warning message to console.
+#
+# @param msg [String] message to output
+def puts_warning(msg)
+  $stdout.puts "\e[33m[WARNING] #{msg}\e[0m" if Calamum::Config[:debug]
+end
+
+# Output error message to console.
+#
+# @param msg [String] message to output
+def puts_error(msg)
+  $stderr.puts "\e[31m[ERROR] #{msg}\e[0m" if Calamum::Config[:debug]
+  exit(1)
+end

data/lib/calamum/resource.rb

@@ -0,0 +1,47 @@
+# This class represents a single resource.
+# It contains attributes from parsed definition.
+# So anywhere in view template we can use this object.
+class Calamum::Resource
+  attr_accessor :uri, :action, :headers,
+    :auth, :params, :errors, :description, :response
+
+  # Initialize object from attributes.
+  #
+  # @param attrs [Hash] attributes to set
+  def initialize(attrs)
+    @uri = attrs['uri']
+    @action = attrs['action'].upcase
+    @headers = attrs['headers'] || {}
+    @auth = !!attrs['authentication']
+    @params = attrs['params'] || {}
+    @errors = attrs['errors'] || {}
+    @description = attrs['description']
+    @response = attrs['response']
+  end
+  
+  # @override
+  # Returns a string representing a label css class.
+  #
+  # @return [String] css class
+  def action_label
+    case @action
+    when 'GET'
+      'label-info'
+    when 'POST'
+      'label-success'
+    when 'PUT'
+      'label-warning'
+    when 'DELETE'
+      'label-important'
+    end
+  end
+
+  # @override
+  # Returns a string representing a resource.
+  #
+  # @return [String] resource in a form (action: uri)
+  def to_s
+    "#{action}: #{uri}"
+  end
+
+end

data/lib/calamum/runner.rb

@@ -3,89 +3,114 @@ require 'calamum/config'
 require 'calamum/doc_generator'
 require 'mixlib/cli'
 
+# Provides a class-based command line opts.
+# See https://github.com/opscode/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",
+    :short        => '-h',
+    :long         => '--help',
+    :description  => 'Show this help',
     :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 :source,
+    :short        => '-f DEFINITION',
+    :long         => '--file DEFINITION',
+    :description  => 'Path to the file with JSON API definition',
+    :required     => true
 
   option :template,
-    :short        => "-t TEMPLATE",
-    :long         => "--template TEMPLATE",
-    :description  => "Documentation HTML template",
-    :default      =>  "bootstrap"
+    :short        => '-t TEMPLATE',
+    :long         => '--template TEMPLATE',
+    :description  => 'Name of HTML template [twitter, bootstrap](twitter by default)',
+    :default      => 'twitter'
 
   option :path,
-    :short        => "-p PATH",
-    :long         => "--path PATH",
-    :description  => "The distination path for the generated doc directory",
-    :default      =>  ENV['HOME']
+    :short        => '-p PATH',
+    :long         => '--path PATH',
+    :description  => 'Path to the directory where docs will be generated',
+    :default      => ENV['HOME']
 
+  option :debug,
+    :short        => '-d',
+    :long         => '--debug',
+    :description  => 'Show actions to do (true by default)',
+    :default      => true,
+    :boolean      => true,
+    :proc         => lambda { |x| true }
+
+  option :version,
+    :short        => '-v',
+    :long         => '--version',
+    :description  => 'Show version number',
+    :proc         => lambda { |x| puts Calamum::VERSION },
+    :exit         => 0
+    
   option :sort,
     :short        => "-s",
     :long         => "--sort",
     :description  => "Sort the resources alphabetically",
     :boolean      => true,
     :default      => false
-
+    
+  # Parses command line options and generates API documentation.
+  # See samples for details how to define meta-data for your API.
   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, @definition.get_description)
-    html_output.save_result(File.join(Calamum::Config[:path], 'doc', 'index.html'))
+    parse_options
+    Calamum::Config.apply(config)
+    @definition = Calamum::DocParser.new(load_source)
+    @definition.load_resources
+    Calamum::DocGenerator.init_base_dir
+    process_index 
+    process_pages if config[:template] == 'twitter'
+  rescue => ex
+    puts_error ex.message
   end
 
-  def load_definition_file
-    begin
-       YAML.load(File.open(config[:definition]))
-    rescue => e
-      puts_error e.message
+  # Open and load the source file of api definition
+  def load_source
+    case File.extname(config[:source])
+    when '.json'
+      Yajl.load(File.open(config[:source]))
+    when '.yml'
+      YAML.load(File.open(config[:source]))
+    else
+      raise 'unknown source file extension'
     end
   end
+  
+  # Bind values to index page and save it.
+  def process_index
+    bindings = {
+      :url => @definition.get_url,
+      :name => @definition.get_name,
+      :resources => @definition.resources,
+      :description => @definition.get_description,
+      :version => @definition.get_version
+    }
+
+    page = Calamum::DocGenerator.new(:index)
+    page.save_template('index.html', bindings)
+  end
+
+  # Bind values to view pages and save them.
+  def process_pages
+    bindings = {
+      :name => @definition.get_name,
+      :version => @definition.get_version
+    }
 
-  def load_options
-    begin
-      parse_options
-    rescue => e
-      puts_error e.message
+    page = Calamum::DocGenerator.new(:view)
+    @definition.resources.each do |methods|
+      methods[1].each do |resource|
+        bindings.merge!(:resource => resource)
+        filename = "#{resource.object_id}.html"
+        page.save_template(filename, bindings)
+      end
     end
   end