yard-rest-plugin 0.1.0

data/Rakefile

@@ -0,0 +1,31 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "yard-rest-plugin"
+    gem.summary = %Q{A plugin for Yardoc that produces API documentation for Restful web services}
+    gem.description = %Q{A plugin for Yardoc that produces API documentation for Restful web services}
+    gem.email = "aisha.fenton@visfleet.com"
+    gem.homepage = "http://github.com/visfleet/yard-rest-plugin"
+    gem.authors = ["Aisha Fenton"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+namespace :ex do
+  desc "Generate example docs"
+  task :generate do
+    `yardoc 'example/*.rb' -t rest --backtrace -p ./templates -e ./lib/yard_rest_plugin.rb -r example/README.markdown --title 'Sample API'`
+  end
+
+  desc "Clean example docs"
+  task :clean do
+    `rm -R doc`
+    `rm -R .yardoc`
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/example/README.markdown

@@ -0,0 +1,11 @@
+Sample API
+==========
+This is a sample API. You should see:
+
+  - This file
+  - An index containing one service /sample.
+  - That service should contain only one action: Index
+  - Index should have a description, list of arguments, an example response, and a list of response fields. 
+  - Nothing else should be included because it doesn't have a URL specified.
+  
+Click [here](./_index.html) to go to the Index

data/example/SampleController.rb

@@ -0,0 +1,84 @@
+##
+# The Sample sevices let you list, create, update, and delete Samples from our application.
+# @url /sample
+#
+class SampleController
+
+  ##
+  # Retuns all samples, as XML, for the current user that match the given parameters.
+  # 
+  # @url
+  # [GET] /samples/index.[format]?[arguments]
+  # 
+  # @argument [String] format Only "xml" is support at this time.
+  # @argument [String] name The name of the sample
+  # @argument [String] reource The resource that sample belongs to
+  # @argument ["@assigned"|"@complete"|"!@complete"] search Return jobs that are assigned, complete, or
+  #   uncomplete.
+  # 
+  # @example_response
+  #   <samples type="array">
+  #     <sample>
+  #       <id>961</id>
+  #       <name>My Sample</name>
+  #       <state>complete</state>
+  #       <last_unassigned_user_id type="integer"></last_unassigned_user_id>
+  #       <resource_id type="integer">127</resource_id>
+  #       <notes></notes>
+  #       <updated_at type="datetime">2010-03-09T20:43:29Z</updated_at>
+  #       <created_at type="datetime">2010-03-09T20:43:16Z</created_at>
+  #     </interval>
+  #   <intervals>
+  # 
+  # @response_field id A unique ID identifying the Sample
+  # @response_field name The name of the sample
+  # @response_field state The current status of the Sample. Can be complete, uncomplete, etc.
+  # @response_field notes Any notes given for the sample
+  # @response_field updated_at The Date/Time (in ISO8601) that the Sample was last updated
+  # @response_field created_at The Date/Time (in ISO8601) that the Sample was created
+  # 
+  def index
+  end
+
+  ##
+  #
+  # Shouldn't be included
+  def show
+  end
+
+  ##
+  # Creates a new Sample
+  # @url [POST] /new
+  # @url [POST] /really_new
+  # 
+  def create
+  end
+
+end
+
+##
+# This one shouldn't show.
+#
+class BogusController
+end
+
+module First
+  module Second
+    
+    ##
+    # Third level deep namespace class
+    # @url /otherpath/third
+    #
+    class Third
+      
+      ##
+      # Does action!
+      # @url [PUT] /otherpath/third/action
+      # 
+      def action
+      end
+      
+    end
+
+  end
+end

data/lib/yard_rest_plugin.rb

@@ -0,0 +1,14 @@
+# Needed because running outside Gem
+# XXX Is there a better way to deal with this?
+$LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__)))
+
+require "yard_rest_plugin/base_helper"
+
+YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + '/../templates'
+
+# Define custom tags
+YARD::Tags::Library.define_tag("URL for Service", :url)
+YARD::Tags::Library.define_tag("Arguments", :argument, :with_types_and_name)
+YARD::Tags::Library.define_tag("Example Respones", :example_response)
+YARD::Tags::Library.define_tag("Response Field", :response_field, :with_name)
+

data/lib/yard_rest_plugin/base_helper.rb

@@ -0,0 +1,18 @@
+module YARD::Templates::Helpers
+  module BaseHelper
+
+    # Adds additional test that only includes Objects that contain a URL tag
+    def run_verifier(list)
+      if options[:verifier]
+        list = list.reject {|item| options[:verifier].call(item).is_a?(FalseClass) }
+      end
+
+      reject_without_url(list)
+    end
+
+    def reject_without_url(list)
+      list.reject {|object| object.tags("url").empty? }
+    end
+  
+  end
+end

data/templates/rest/class/html/setup.rb

@@ -0,0 +1 @@
+include T('rest/module/html')

data/templates/rest/docstring/html/setup.rb

@@ -0,0 +1,4 @@
+def init
+  return if object.docstring.blank?
+  sections :text, T('tags')
+end

data/templates/rest/docstring/html/text.erb

@@ -0,0 +1 @@
+<%= htmlify(object.docstring.strip) %>

data/templates/rest/fulldoc/html/css/common.css

@@ -0,0 +1 @@
+/* Override this file with custom rules */

data/templates/rest/fulldoc/html/css/full_list.css

@@ -0,0 +1,78 @@
+body {
+  font-family:"Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif;
+  font-size:13px;
+  height:101%;
+  overflow-x:hidden;
+  margin:0;
+}
+
+h1 {
+  font-size:1.4em;
+  margin:0;
+  padding:12px 10px 0;
+}
+
+.clear { clear:both; }
+
+#search {
+  position:absolute;
+  right:5px;
+  top:9px;
+}
+
+#full_list {
+  list-style:none;
+  margin-left:0;
+  padding:0;
+}
+
+#full_list ul { padding:0; }
+
+#full_list li {
+  font-size:1.1em;
+  list-style:none;
+  margin:0;
+  padding:5px 5px 5px 12px;
+}
+
+#noresults {
+  display:none;
+  padding:7px 12px;
+}
+
+li {
+  color:#888;
+  cursor:pointer;
+}
+
+li.r1 { background: #fafafa; }
+li.r2 { background: #f0f0f0; }
+
+li:hover { background:#ddd; }
+
+a:link,a:visited {
+  text-decoration:none;
+  color:#05a;
+}
+
+li.clicked {
+  background:#05a;
+  color:#ccc;
+}
+
+li.clicked a:link,li.clicked a:visited {
+  color:#eee;
+}
+
+#search input {
+  border:1px solid #bbb;
+  -moz-border-radius:3px;
+  -webkit-border-radius:3px;
+}
+
+#full_list.insearch li.found {
+  display:list-item;
+  padding-left:10px;
+}
+
+#full_list.insearch li { display:none; }

data/templates/rest/fulldoc/html/css/style.css

@@ -0,0 +1,225 @@
+body { 
+  padding: 0 20px;
+  font-family: "Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif; 
+  font-size: 13px;
+}
+
+h1 {
+  font-size: 25px; 
+  margin: 1em 0 0.5em; 
+  padding-top: 4px; 
+}
+
+h1.noborder { 
+  border-top: 0px; 
+  margin-top: 0; 
+  padding-top: 4px; 
+}
+
+h1.title { margin-bottom: 10px; }
+
+h1.alphaindex { 
+  margin-top: 0; 
+  font-size: 22px; 
+}
+
+h1 .minor_heading { color: #777777; }
+
+h2 { 
+  padding: 0;
+  padding-bottom: 3px;
+  border-bottom: 1px #aaa solid;
+  font-size: 1.4em;
+  margin: 1.8em 0 0.5em;
+}
+
+.inline { display: inline; }
+.inline p:first-child { display: inline; }
+
+h3.inherited {
+  font-style: italic;
+  font-family: "Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif;
+  font-weight: normal;
+  padding: 0;
+  margin: 0;
+  margin-top: 12px;
+  margin-bottom: 3px;
+  font-size: 13px;
+}
+p.inherited {
+  padding: 0;
+  margin: 0;
+  margin-left: 25px;
+}
+
+/* Content */
+#content a:link, #content a:visited { 
+  text-decoration: none; 
+  color: #05a; 
+}
+#content a:hover { 
+  background: #ffffa5; 
+}
+
+/* Index files listing */
+#files { 
+  padding-left: 15px; 
+  font-size: 1.1em; 
+  padding: 0; 
+}
+#files li { 
+  list-style: none; 
+  display: inline; 
+  padding: 7px 12px; 
+  line-height: 35px; 
+}
+
+.method_details { 
+  border-top: 1px dotted #aaa; 
+  margin-top: 15px; 
+  padding-top: 0; 
+}
+.method_details.first { border: 0; }
+
+ul.signature { 
+  font-size: 1.1em; 
+  font-weight: normal; 
+  font-family: Monaco, Consolas, Courier, monospace; 
+  padding: 6px 10px; 
+  margin-top: 18px; 
+  background: #e5e8ff; 
+  border: 1px solid #d8d8e5; 
+  -moz-border-radius: 3px; 
+  -webkit-border-radius: 3px;
+  list-style: none;
+}
+
+/* All tags */
+.tags { margin-bottom: 12px; }
+.tags h3 { 
+  font-size: 1em; 
+  margin-bottom: 0; 
+}
+.tags ul { 
+  margin-top: 5px; 
+  padding-left: 30px; 
+  list-style: square; 
+}
+.tags ul li { 
+  margin-bottom: 3px; 
+}
+.tags ul .name { 
+  font-family: monospace; 
+  font-weight: bold; 
+}
+.tags ul p.note { padding: 3px 6px; }
+
+/* Repsonse example tag */
+.tags .examples h3 { margin-bottom: 10px; }
+.tags .examples h4 { 
+  padding: 0; 
+  margin: 0; 
+  margin-left: 15px; 
+  font-weight: bold; 
+  font-size: 0.9em; 
+}
+.tags .example { 
+  padding: 5px 12px; 
+  margin-top: 4px; 
+  border: 1px solid #eef; 
+  background: #f5f5ff;
+}
+
+
+/* Search menu */
+#search { 
+  position: absolute; 
+  right: 14px; 
+  top: 0px; 
+}
+#search a:link, #search a:visited { 
+  display: block; float: left; margin-right: 4px;
+  padding: 8px 10px; text-decoration: none; color: #05a; background: #eaeaff;
+  border: 1px solid #d8d8e5;
+  -moz-border-radius-bottomleft: 3px; -moz-border-radius-bottomright: 3px; 
+  -webkit-border-bottom-left-radius: 3px; -webkit-border-bottom-right-radius: 3px;
+}
+#search a:hover { 
+  background: #eef; 
+  color: #06b; 
+}
+#search a.active { 
+  background: #568; padding-bottom: 20px; color: #fff; border: 1px solid #457; 
+  -moz-border-radius-topleft: 5px; -moz-border-radius-topright: 5px;
+  -webkit-border-top-left-radius: 5px; -webkit-border-top-right-radius: 5px;
+}
+#search a.inactive { 
+  color: #999; 
+}
+
+/* Search frame */
+#search_frame {
+  background: #fff;
+  display: none;
+  position: absolute; 
+  top: 36px; 
+  right: 18px;
+  width: 500px;
+  height: 80%;
+  overflow-y: scroll;
+  border: 1px solid #999;
+  border-collapse: collapse;
+  -webkit-box-shadow: -2px 5px 25px #aaa;
+  -moz-box-shadow: -2px 5px 25px #aaa;
+  -moz-border-radius: 2px;
+  -webkit-border-radius: 2px;
+}
+
+/* Footer */
+#footer { 
+  margin-top: 15px; 
+  border-top: 1px solid #ccc; 
+  text-align: center; 
+  padding: 7px 0; 
+  color: #999; 
+}
+
+/* Alphabetal Index Listing */
+#listing ul.alpha { font-size: 1.1em; }
+#listing ul.alpha { margin: 0; padding: 0; padding-bottom: 10px; list-style: none; }
+#listing ul.alpha li.letter { font-size: 1.4em; padding-bottom: 10px; }
+#listing ul.alpha ul { margin: 0; padding-left: 15px; }
+
+li.r1 { background: #f0f0f0; }
+li.r2 { background: #fafafa; }
+
+/* Note tag */
+.note { 
+  color: #222;
+  -moz-border-radius: 3px; 
+  -webkit-border-radius: 3px; 
+  background: #e3e4e3; 
+  border: 1px solid #d5d5d5; 
+  padding: 7px 10px;
+}
+.note.todo { 
+  background: #ffffc5; 
+  border-color: #ececaa; 
+}
+.note.title { 
+  text-transform: lowercase; 
+  padding: 1px 5px; 
+  margin-left: 5px; 
+  font-size: 0.9em; 
+  font-family: "Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif; 
+}
+h1 .note.title { 
+  font-size: 0.5em; 
+  font-weight: normal; 
+  padding: 3px 5px; 
+  position: relative; 
+  top: -3px; 
+  text-transform: capitalize; 
+}
+
+