jaxrsdoc 0.0.1

data/bin/jaxrsdoc

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+require File.expand_path("../../lib/parse.rb", __FILE__)
+require File.expand_path("../../lib/site.rb", __FILE__)
+require 'optparse'
+require "rexml/document"
+
+options = {}
+optparse = OptionParser.new do |opts|
+  opts.banner = "USAGE\n jaxrsdoc [options] source_location"
+  opts.separator "\nOPTIONS\n"
+  
+  options[:pattern] = "*Resource.java"
+  opts.on( '-p', '--pattern PATTERN', 'Naming pattern of your Jaxrs annotated files java resources. Default is: "*Resource.java".' ) do |pattern|
+    options[:pattern] = pattern
+  end
+
+  opts.on( '-m', '--maven', 'Indicates a maven project. Project name & version will be derived the pom.xml at the directory level' ) do |maven|
+    options[:maven] = true
+  end
+
+  opts.on( '-a', '--artifact ARTIFACT', 'Name of the artifact/project/module to be included on the website banner.' ) do |artifact_name|
+    options[:artifact_name] = artifact_name
+  end
+
+  opts.on( '-v', '--version VERSION', 'Version of your artifact/project/module to be included on the website banner.' ) do |artifact_version|
+    options[:artifact_version] = artifact_version
+  end
+  
+  opts.on( '-h', '--help', 'Display this screen' ) do
+    puts opts
+    exit
+  end
+end
+
+begin
+  optparse.parse!
+rescue OptionParser::InvalidOption, OptionParser::InvalidArgument, OptionParser::MissingArgument
+  puts "#{$!.message}"
+  puts "try 'jaxrsdoc -h' for more information"
+  exit
+end
+
+resources_location = ARGV.first
+
+puts "Looking files recursively at #{resources_location}"
+matched_files = Dir.glob("#{resources_location}/**/#{options[:pattern]}").select{ |entry| File.file?(entry) }
+puts "Found #{matched_files.size} files matching '#{options[:pattern]}'"
+
+processed_resources = matched_files.map {|file| 
+  JaxrsDoc::ResourceParser.parse(File.new(file))
+}.select {|resource| resource.valid? and not resource.nil? }
+puts "Processed #{processed_resources.size} files with a @Path type annotation"
+
+project_version = options[:artifact_version]
+project_name = options[:artifact_name]
+
+if(options[:maven]) then
+  puts "Looking for a pom.xml file at #{resources_location}"
+  pom_xml = Dir.glob("#{resources_location}/pom.xml").first
+  pom = REXML::Document.new File.new(pom_xml)
+  project_name = pom.elements["//artifactId"].first 
+  project_version = pom.elements["//version"].first
+  puts "Found maven project with name: #{project_name}, version: #{project_version}"
+end
+
+output_dir = JaxrsDoc::Site.new(processed_resources, Dir.pwd, {:project_version => project_version, :project_name => project_name}).generate
+
+puts "Site generated. Open #{output_dir.path}/index.html"
+
+

data/lib/annotations.rb

@@ -0,0 +1,104 @@
+module JaxrsDoc
+  
+  class Resource
+    include Comparable
+    
+    attr_reader :name, :description, :params_descriptions, :path, :verbs, :gets, :posts, :puts, :deletes, :consumes
+    
+    def initialize(file_name, type_annotations, verbs_annotations = {}, type_description = nil, params_descriptions = {})
+      @name = file_name
+      @description = type_description
+      @params_descriptions = params_descriptions
+      @path = type_annotations.annotations.find {|a| a.name.eql?"Path"}
+      @consumes = type_annotations.annotations.find {|a| a.name.eql?"Consumes"}
+      @gets = verbs_annotations[:gets]
+      @posts = verbs_annotations[:posts]
+      @puts = verbs_annotations[:puts]
+      @deletes = verbs_annotations[:deletes]
+      @verbs = verbs_annotations
+    end
+    
+    def valid?
+      not @path.nil?
+    end
+    
+    def add_param_description(param_description)
+      @params_descriptions.update(param_description)
+    end
+    
+    def <=>(another)
+      path.value <=> another.path.value
+    end
+    
+    def to_s
+      "#{@name} [#{@path.value}]"  
+    end
+    
+    # Support ERB templating of member data.
+    def get_binding
+      binding
+    end
+    
+  end
+  
+  class AnnotationsGroup
+    
+    attr_reader :annotations
+    
+    def initialize(annotations = [])
+      @annotations = Array.new(annotations)
+    end
+    
+    def method_missing(method_name, *args)
+      if(method_name.to_s.include?"params")
+        @annotations.select{|a| /\b(Form|FormData|Query)Param\b/ =~ a.name }
+      else
+        @annotations.find {|a| method_name.to_s.eql?(a.name.downcase) }
+      end
+    end
+    
+    def empty?
+      @annotations.empty?
+    end
+    
+    def size
+      @annotations.size
+    end
+    
+    def to_s
+      @annotations.to_s
+    end
+
+  end
+  
+  
+  class Annotation
+    
+    attr_reader :name, :values, :value
+    
+    def initialize(annotation_text)
+      @text = annotation_text.strip
+      @name = @text.delete("@").split("(")[0]
+      parse_values
+    end
+    
+    def to_s
+      @text
+    end
+    
+    private
+    
+    def parse_values
+      @values = []
+      if(matches = /\((.*)\)/.match(@text))
+        tokens = matches[1].split(",")
+        tokens.each { |v|
+          @values << v.gsub(/\"|'/, "").strip
+        }
+        @value = tokens.first.gsub(/\"|'/, "").strip 
+      end
+    end
+    
+  end
+
+end

data/lib/jaxrsdoc_version.rb

@@ -0,0 +1,3 @@
+module JaxrsDoc
+  VERSION = '0.0.1'
+end

data/lib/parse.rb

@@ -0,0 +1,91 @@
+require File.expand_path("../annotations.rb", __FILE__)
+
+module JaxrsDoc
+  
+  module AnnotationScanner
+    
+    JAXRS_ANNOTATIONS = %w[ ApplicationPath Consumes CookieParam DefaultValue 
+                            DELETE Encoded FormParam FormDataParam GET HEAD HeaderParam 
+                            HttpMethod MatrixParam OPTIONS Path PathParam
+                            POST Produces PUT QueryParam ]
+        
+    def self.scan_annotations(text)
+      annotations = []
+      text.scan(jaxrs_annotations_regexp) {|s| annotations << JaxrsDoc::Annotation.new(s.first)}
+      JaxrsDoc::AnnotationsGroup.new(annotations)
+    end
+    
+    private 
+    
+    def self.jaxrs_annotations_regexp
+      regexp = JAXRS_ANNOTATIONS.map { |a|
+        ["#{a}(?=[[:space:]])", "#{a}\\(?.*?\\)"]
+      }
+      Regexp.new("@(#{regexp.join('|')})")
+    end
+    
+  end
+  
+  module ParamDescriptionScanner
+    
+    def self.scan_params_descriptions(text)
+      params_descriptions = Hash.new("")
+      text.each_line { |line|
+        if(param_index = line.index("@param"))
+          param_name, param_desc = line[(param_index + 6)..-1].split(" ", 2);
+          params_descriptions.store(param_name, param_desc)
+        end
+      }
+      params_descriptions
+    end
+    
+  end 
+  
+  module ResourceParser
+    include AnnotationScanner
+    
+    def self.parse(file)
+      @filename = File.basename(file.path)
+      parse_content(file.read)
+    end
+    
+    def self.parse_content(text)
+      verbs_annotations = {:gets => [], :posts => [], :puts => [], :deletes => []}
+      descriptions = {}
+      java_sections = text.split(/(?<=\s)({)/);
+      resource_head_section = java_sections.shift
+      type_annotations = AnnotationScanner.scan_annotations(resource_head_section)
+      descriptions.update(ParamDescriptionScanner.scan_params_descriptions(resource_head_section))
+      type_description = parse_resource_description(resource_head_section)
+      java_sections.each { |section| 
+        group = AnnotationScanner.scan_annotations(section)
+        descriptions.update(ParamDescriptionScanner.scan_params_descriptions(section))
+        unless group.empty?
+          verbs_annotations[:gets] << group if(group.get)
+          verbs_annotations[:posts] << group if(group.post)
+          verbs_annotations[:puts] << group if(group.put)
+          verbs_annotations[:deletes] << group if(group.delete)
+        end
+      }
+      JaxrsDoc::Resource.new(@filename, type_annotations, verbs_annotations, type_description, descriptions)
+    end 
+    
+    private
+    
+    def self.parse_resource_description(head_text_section)
+      from_package_only_head_section = head_text_section.each_line.drop_while {|line|
+        not line.strip.start_with?("package")
+      }.join
+      
+      if (description_match = /^\/\*\*(.+)\*\/$/m.match(from_package_only_head_section))
+        full_text = description_match[1].gsub("*", "")
+        description = ""
+        full_text.each_line { |line|
+          description << line unless line.include?("@param")
+        }
+        description
+      end      
+    end
+         
+  end
+end

data/lib/site.rb

@@ -0,0 +1,60 @@
+require File.expand_path("../templates.rb", __FILE__)
+require 'erb'
+require 'fileutils'
+
+module JaxrsDoc
+  
+  class Site
+    
+    attr_reader :resources, :project_version, :project_name, :output_dir
+    
+    def initialize(resources, output_location, options = {})
+      @resources = resources.sort!
+      @project_version = options[:project_version]
+      @project_name = options[:project_name]
+      make_output_dir(output_location)
+      copy_resources_to_output_dir
+    end
+    
+    def generate
+      @resources.each { |resource|
+        File.open(resource_file_path(resource.name), "w") { |f|
+            content = ERB.new(JaxrsDoc::Templates.get_resource_page).result(binding)
+            f.syswrite(content)
+        }
+      }
+      
+      File.open(index_file_path, "w") { |f|
+          content = ERB.new(JaxrsDoc::Templates.get_index_page).result(binding)
+          f.syswrite(content)
+      }
+      @output_dir
+    end
+    
+    private
+    
+    def resource_file_path(resource_name)
+      File.join(@output_dir.path, "#{resource_name}.html")
+    end
+    
+    def index_file_path
+      File.join(@output_dir.path, "index.html")
+    end
+    
+    def make_output_dir(output_location)
+      output_path = "#{output_location}"
+      output_path << "/jaxrsdoc"
+      output_path << "/#{@project_name}" unless @project_name.nil?
+      output_path << "/#{@project_version}" unless @project_version.nil?
+      FileUtils.mkdir_p(output_path)
+      @output_dir = Dir.new(output_path)
+    end
+
+    def copy_resources_to_output_dir
+      bootstrap_file_path = File.expand_path("../../site/bootstrap.css", __FILE__)
+      jaxrsdoc_css_file_path = File.expand_path("../../site/jaxrsdoc.css", __FILE__)
+      FileUtils.cp(bootstrap_file_path, File.join(@output_dir.path, "bootstrap.css"))
+      FileUtils.cp(jaxrsdoc_css_file_path, File.join(@output_dir.path, "jaxrsdoc.css"))
+    end
+  end    
+end

data/lib/templates.rb

@@ -0,0 +1,208 @@
+module JaxrsDoc
+  
+  module Templates
+    
+    def self.get_index_page
+      %q{
+        <html>
+          <head>
+            <link rel="stylesheet" type="text/css" href="bootstrap.css" />
+            <link rel="stylesheet" type="text/css" href="jaxrsdoc.css" />
+          </head>
+          <body>
+            <div class="navbar">
+              <div class="navbar-inner">
+                <div class="container">
+                  <a class="brand" href="#"><%= @project_name %> <%= @project_version %></a>
+                  <ul class="nav">
+                    <li class="active"><a href="index.html">API index</a></li>
+                  </ul>
+                  <p class="navbar-text pull-right">Last update <%= Time.now.strftime("%d %B - %H:%M:%S") %></p>
+                </div>
+              </div>
+            </div>
+            <div class="container">
+              <% @resources.each_slice(20) do |big_packets_of_resources| %>
+                <div class="row">
+                <% big_packets_of_resources.each_slice(10) do |small_packets_of_resources|%>
+                  <div class="span6">
+                    <pre><ul><% small_packets_of_resources.each do |resource|%><li><a href="<%= resource.name %>.html"> <% if resource.path %><%= resource.path.value %><% end %></a></li><% end%></ul></pre>
+                  </div>
+                <% end %>
+                </div>
+              <% end%>
+            <footer class="modal-footer"><span>Powered by <a href="https://github.com/simcap/jaxrsdoc">Jaxrsdoc</a></span></footer>  
+            </div>
+          <body>
+        </html>
+       }
+    end
+    
+    def self.get_resource_page
+      %q{
+      <html>
+        <head>
+          <link rel="stylesheet" type="text/css" href="bootstrap.css" />
+          <link rel="stylesheet" type="text/css" href="jaxrsdoc.css" />
+        </head>
+        <body>
+          <div class="navbar">
+            <div class="navbar-inner">
+              <div class="container">
+                <a class="brand" href="#"><%= @project_name %> <%= @project_version %></a>
+                <ul class="nav">
+                  <li class="active"><a href="index.html">API index</a></li>
+                </ul>
+                <p class="navbar-text pull-right">Updated <%= Time.now.strftime("%d %B - %H:%M:%S") %></p>
+              </div>
+            </div>
+          </div>
+    
+          <div class="container">
+          
+            <div class="page-header">	
+        	     <h1><% if resource.path %><%= resource.path.value %><% end %><pre class="pull-right"><%= resource.name %></pre></h1>
+            </div>
+            
+            <% if resource.description %>
+            <div>
+              <pre><%= resource.description %></pre>
+            </div>
+            <% end %>
+    
+            <% resource.gets.each do |annot_group| %>
+              <div class="row">	
+            		<div class="get span12">
+                    <button class="btn btn-success pull-left disabled" href="#"><%= annot_group.get.name %></button>
+                    <h3 class="pagination-centered"><% if annot_group.path %> <%= annot_group.path.value %> <% end %></h3>
+                  </div>	
+               </div>
+
+        	     <% unless annot_group.queryparams.empty? %>
+               <div class="row">	
+             		<div class="span12">
+                  <table class="table table-bordered table-striped">
+            		   <colgroup>
+            		    <col class="span1">
+            		   </colgroup>
+            	     <thead>
+            		   <tr><th>Parameter</th><th>Description</th></tr>
+            	     </thead>
+            	     <tbody>
+            	       <% annot_group.queryparams.each do |param| %>
+                       <tr>
+                        <td><%= param.value %></td>
+                        <td><%= resource.params_descriptions[param.value] %></td>
+                       </tr>
+                     <% end %>
+                   </tbody>
+                  </table>
+                  </div>	
+               </div>
+               <% end %>
+            <% end %>
+      
+            <% resource.posts.each do |annot_group| %>
+              <div class="row">	
+            		<div class="post span12">
+                    <button class="btn btn-info pull-left disabled" href="#"><%= annot_group.post.name %></button>
+                    <h3 class="pagination-centered"><% if annot_group.path %> <%= annot_group.path.value %> <% end %></h3>
+                  </div>	
+               </div>
+
+         	     <% unless annot_group.params.empty? %>
+               <div class="row">	
+             		<div class="span12">
+                  <table class="table table-bordered table-striped">
+            		   <colgroup>
+            		    <col class="span1">
+            		   </colgroup>
+            	     <thead>
+            		   <tr><th>Parameter</th><th>Description</th></tr>
+            	     </thead>
+                   <tbody>
+             	       <% annot_group.params.each do |param| %>
+                        <tr>
+                         <td><%= param.value %></td>
+                         <td><%= resource.params_descriptions[param.value] %></td>
+                        </tr>
+                    <% end %>
+                    </tbody>
+                  </table>
+                  </div>	
+               </div>
+               <% end %>
+            <% end %>
+            
+            <% resource.puts.each do |annot_group| %>
+              <div class="row">	
+            		<div class="put span12">
+                    <button class="btn btn-warning pull-left disabled" href="#"><%= annot_group.put.name %></button>
+                    <h3 class="pagination-centered"><% if annot_group.path %> <%= annot_group.path.value %> <% end %></h3>
+                  </div>	
+               </div>
+
+         	     <% unless annot_group.params.empty? %>
+               <div class="row">	
+             		<div class="span12">
+                  <table class="table table-bordered table-striped">
+            		   <colgroup>
+            		    <col class="span1">
+            		   </colgroup>
+            	     <thead>
+            		   <tr><th>Parameter</th><th>Description</th></tr>
+            	     </thead>
+                   <tbody>
+             	       <% annot_group.params.each do |param| %>
+                        <tr>
+                         <td><%= param.value %></td>
+                         <td><%= resource.params_descriptions[param.value] %></td>
+                        </tr>
+                    <% end %>
+                    </tbody>
+                  </table>
+                  </div>	
+               </div>
+               <% end %>
+            <% end %>
+            
+            <% resource.deletes.each do |annot_group| %>
+              <div class="row">	
+            		<div class="post span12">
+                    <button class="btn btn-danger pull-left disabled" href="#"><%= annot_group.delete.name %></button>
+                    <h3 class="pagination-centered"><% if annot_group.path %> <%= annot_group.path.value %> <% end %></h3>
+                  </div>	
+               </div>
+
+         	     <% unless annot_group.params.empty? %>
+               <div class="row">	
+             		<div class="span12">
+                  <table class="table table-bordered table-striped">
+            		   <colgroup>
+            		    <col class="span1">
+            		   </colgroup>
+            	     <thead>
+            		   <tr><th>Parameter</th><th>Description</th></tr>
+            	     </thead>
+                   <tbody>
+             	       <% annot_group.params.each do |param| %>
+                        <tr>
+                         <td><%= param.value %></td>
+                         <td><%= resource.params_descriptions[param.value] %></td>
+                        </tr>
+                    <% end %>
+                    </tbody>
+                  </table>
+                  </div>	
+               </div>
+               <% end %>
+            <% end %>
+            
+            
+          </div>
+        <body>
+      </html>
+    }
+  end
+ end
+end