yard-rest 1.0.1 → 1.0.2

data/Rakefile

@@ -11,7 +11,7 @@ begin
     gem.homepage = "https://github.com/spape/yard-rest-plugin"
     gem.authors = ['R. Kevin Nelson', 'Aisha Fenton', 'Sebastian Pape']
     gem.add_dependency("yard", '~>0.7.4')
-    gem.files = Dir.glob("{lib,example,templates/rest}/**/*.*").concat(["Rakefile"])
+    gem.files = Dir.glob("{lib,example,templates/rest}/**/*").concat(["Rakefile"])
     gem.extra_rdoc_files = ['VERSION', 'README.markdown']
   end
   Jeweler::GemcutterTasks.new

data/VERSION

@@ -1 +1 @@
-1.0.1
+1.0.2

data/example/doc/README_FOR_API

@@ -0,0 +1,12 @@
+## Introduction
+Welcome to the API documentation.
+
+## Quick Example
+/examples.json
+This returns a list of examples.
+
+## JSON as Standard Format
+Our standard format for the API is JSON. To communicate to the API you have to set the format explicitly on each request.  
+### How to send JSON-Requests
+    /examples.json
+    /examples (with Header: "Accept: application/json")

data/templates/rest/class/html/header.erb

@@ -0,0 +1,18 @@
+<div class="service">
+  <h1 class="noborder title"><%= options[:title] %></h1>
+    <a class="back" href="<%= url_for('index.html') %>" title="back to the overview">&laquo; back to overview</a>
+    <h2><%= object.name.to_s.gsub(/Controller/,"") %></h2>
+    <%= yieldall %>
+</div>
+
+
+
+
+
+
+
+
+
+
+
+

data/templates/rest/class/html/method_details_list.erb

@@ -0,0 +1,80 @@
+<% unless @meths.empty? %>
+  <div id="Services" class="method_details_list">
+    <% @meths.each_with_index do |meth, i| %>
+		<div class="method">
+			<p class="method_desc"><%= meth.docstring %></p>
+			<h3 class="resource_url"><strong><%= meth.tag(:resource).text %></strong> [<%= meth.tag(:action).text %>]</h3>
+
+			<div class="parameters">	
+				<% if meth.tags(:required).size %>
+					<div class="required">
+						<h4>Required Parameters</h4>
+						<% meth.tags(:required).each do |required| %>
+							<ul>
+								<li>
+									<span class="name"><%= required.name%></span>
+									<span class="type"><%= required.types.join%></span>
+									<span class="text"><%= required.text%></span>
+								</li>
+							</ul>
+						<% end %>
+					</div>
+				<% end %>
+
+				<% if meth.tags(:optional).size %>
+					<div class="optional">
+						<h4>Optional Parameters</h4>
+						<% meth.tags(:optional).each do |optional| %>
+							<ul>
+								<li>
+									<span class="name"><%= optional.name%></span>
+									<span class="type"><%= optional.types.join%></span>
+									<span class="text"><%= optional.text%></span>
+								</li>
+							</ul>
+						<% end %>
+					</div>
+				<% end %>
+			</div><!-- parameters -->
+			
+			<% if meth.tags(:response_field).size %>
+				<div class="response_fields">
+					<h4>Response Fields</h4>
+					<% meth.tags(:response_field).each do |response_field| %>
+						<ul>
+							<li>
+								<span class="name"><%= response_field.name%></span>
+								<span class="type"><%= response_field.types.join%></span>
+								<span class="text"><%= response_field.text%></span>
+							</li>
+						</ul>
+					<% end %>
+				</div>
+			<% end %>
+			
+			<% if meth.tags(:example_request).size %>
+				<div class="examples">
+					<h4>Examples</h4>
+					<% meth.tags(:example_request).each_with_index do |example_request, i| %>
+						<div class="example">
+							<% example_request_description = meth.tags(:example_request_description)[i] %>
+							<% example_response = meth.tags(:example_response)[i] %>
+							<% example_response_description = meth.tags(:example_response_description)[i] %>
+							<span class="description"><%= (example_request_description.nil?) ? "" : example_request_description.text %></span>
+							<span class="hash request">
+								<strong class="type">Request</strong>
+								<%= (example_request.nil?) ? "" : example_request.text %>
+							</span>
+							<span class="hash response">
+								<strong class="type">Response</strong>
+								<%= (example_response.nil?) ? "" : example_response.text %>
+							</span>
+							<span class="description"><%= (example_response_description.nil?) ? "" : example_response_description.text %></span>
+						</div>
+					<% end %>
+				</div>
+			<% end %>
+		</div>	
+    <% end %>
+  </div>
+<% end %>

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

@@ -0,0 +1,16 @@
+def init
+  @page_title = "#{object.name.to_s.gsub(/Controller/,"")} - #{options[:title]}"
+  sections :header, [T('docstring'), :method_details_list, [T('method_details')]]
+end
+
+def method_details_list
+  objects = Array(object)
+  objects_with_resources_tags = index_objects(objects)
+  @meths = []
+  unless objects_with_resources_tags.empty?
+    objects_with_resources_tags.each do |obj|
+      @meths += obj.meths.select{|x| x.has_tag? :resource}
+    end
+  end
+  erb(:method_details_list)
+end

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/full_list_resource.erb

@@ -0,0 +1,5 @@
+<% n = 1 %>
+<% @items.sort_by { |s| s.name.to_s }.each do |resource| %>
+  <li class="r<%= n %>"><%= linkify(resource, resource.name.to_s.gsub(/Controller/, "")) %></li>
+  <% n = n == 2 ? 1 : 2 %>
+<% end %>

data/templates/rest/fulldoc/html/full_list_topic.erb

@@ -0,0 +1,14 @@
+<li><a href="<%= url_for('_index.html') %>">Index</a></li>
+<% n = 1 %>
+<% @topics.sort_by {|s,o| s }.each do |topic,objects| %>
+  <li class="r<%= n %>"><%= topic%></li>
+  <% unless objects.empty? %>
+    <% objects.each do |object| %>
+      <% object.tags("url").each do |url_tag| %>
+        <li class="r<%= n %>"><%= linkify(object, url_tag.text) %></li>
+      <% end %>
+    <% end%>
+  <% end %>
+  <% n = n == 2 ? 1 : 2 %>
+<% end %>
+

data/templates/rest/fulldoc/html/js/rest_plugin.js

@@ -0,0 +1,22 @@
+function resourceSearchFrameLinks() {
+  $('#resource_list_link').click(function() {
+    toggleSearchFrame(this, relpath + 'resource_list.html');
+  });
+}
+
+$(resourceSearchFrameLinks);
+
+/*
+function resourceKeyboardShortcuts() {
+  if (window.top.frames.main) return;
+  $(document).keypress(function(evt) {
+    if (evt.altKey || evt.ctrlKey || evt.metaKey || evt.shiftKey) return;
+    if (typeof evt.orignalTarget !== "undefined" &&  
+        (evt.originalTarget.nodeName == "INPUT" || 
+        evt.originalTarget.nodeName == "TEXTAREA")) return;
+    switch (evt.charCode) {
+      case 82: case 114: $('#resource_list_link').click(); break; // 'r' or 'R'
+    }
+  });
+}
+*/

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

@@ -0,0 +1,23 @@
+include Helpers::ModuleHelper
+include Helpers::FilterHelper
+
+def generate_topic_list
+  topic_objects = index_objects(@objects).reject { |o| o.root? }
+  @topics = {}
+
+  topic_objects.each do |object|
+    object.tags('topic').each { |topic| (@topics[topic.text] ||= []) << object }
+  end
+
+  @list_title = 'Topic List'
+  @list_type = 'topic'
+
+  asset('topic_list.html', erb(:full_list))
+end
+
+def generate_resource_list
+  @items = index_objects(@objects)
+  @list_title = "List of Resources"
+  @list_type = "resource"
+  asset('resource_list.html', erb(:full_list))
+end

data/templates/rest/layout/html/footer.erb

@@ -0,0 +1,3 @@
+<div id="footer">
+  Generated on <%= Time.now.strftime("%c") %> with ruby-<%= RUBY_VERSION %>
+</div>

data/templates/rest/layout/html/index.erb

@@ -0,0 +1,19 @@
+<div id="start">
+  <h1 class="noborder title"><%= options[:title] %></h1>
+
+  <% if @readme %>
+	<%= htmlify(@readme.contents, :markdown) %>
+  <% end %>
+  
+  <h2>All Resources</h2>
+  <ul id="resources">
+	<% unless @resources.nil? %>
+    	<% @resources.sort_by { |s| s.name.to_s }.each do |resource| %>
+      		<li><%= linkify(resource, resource.name.to_s.gsub(/Controller/, "")) %></li>
+    	<% end %>
+    <% end %>
+  </ul>
+
+  <div class="clear"></div>
+
+</div>

data/templates/rest/layout/html/layout.erb

@@ -0,0 +1,210 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <%= erb(:headers) %>
+	<style type="text/css">
+		#toc {top: 24px;}
+		#toc .title {display: none;}
+		#toc a:link, #content a:visited { text-decoration: none; color: #05a; }
+		#toc a:hover { background: #ffffa5; }
+		pre code {
+			display: block;
+			background: #EAF0FF;
+			padding: 12px;
+			line-height: 1.9em;
+		}
+		a.back {
+			font-size: 1.2em;
+			padding: 4px;
+		}
+		p.method_desc {
+			padding: 16px 0 0 14px;
+			font-size: 1.2em;
+		}
+		h2 {
+			margin: 2.4em 0 0.5em;
+		}
+		h2 + p {
+			font-size: 1.2em;
+			margin-bottom: 62px;
+		}
+		.method {
+			display: block;
+			margin-top: 40px;
+			padding-top: 0;
+			position: relative;
+			box-shadow: 0 -6px 12px rgba(0,0,0,0.1);
+		}
+		h3 {
+			font-size: 1.2em;
+			font-weight: normal;
+			padding-top: 6px;
+			margin-bottom: -6px;
+		}
+		h4 {
+			margin: 0;
+		}
+		#resources {
+			padding: 14px 20px 52px;
+		}
+		#resources li {
+			border-right: 1px solid #0055AA;
+			display: block;
+			font-size: 1.4em;
+			float: left;
+			padding-right: 14px;
+			padding-left: 12px;
+		}
+		.resource_url {
+			border: 1px solid white;
+			display: block;
+			background: #EAF0FF;
+			margin-top: 11px;
+			padding: 12px 12px 18px;
+		}
+		#search_frame #search {
+			display: none;
+		}
+		.parameters, .response_fields {
+			background: none repeat scroll 0 0 #EAF0FF;
+		}
+		.parameters .required {
+			background: #d5e1ff;
+			padding: 12px;
+			border: 1px solid white;
+		}
+		.parameters .optional, .response_fields {
+			padding: 18px 12px 12px 12px;
+			border: 1px solid white;
+		}
+		.parameters .optional ul li, .parameters .required li, .response_fields li {
+			display: block;
+			padding: 4px 0 0 6px;
+		}
+		.parameters .optional ul li .name, .parameters .required li .name, .response_fields li .name {
+			font-weight: bold;
+		}
+		.parameters .optional ul li .text, .parameters .required li .text, .response_fields li .text {
+			display: block;
+		}
+		.examples {
+			padding: 32px 12px 12px 12px;
+		}
+		.example {			
+			border-bottom: 1px solid #BBB;
+			display: block;
+			padding: 18px 0 26px;
+			margin-bottom: 14px;
+			margin-top: 8px;
+		}
+		.example .description {
+			display: block;
+			font-size: 1.2em;
+			margin: 8px 0;
+		}
+		
+		.example .hash {
+			display: block;
+			background: #EEF;
+			font-size: 1.1em;
+			border-radius: 4px;
+			box-shadow: inset 0 2px 5px rgba(0,0,0,0.1);
+			padding: 12px;
+		}
+		
+		.example .hash .type {
+			display: block;
+			font-size: 0.8em;
+			color: #99A;
+			padding-bottom: 6px;
+		}
+		
+		.example .hash.request {
+			border-bottom-left-radius: 0;
+			border-bottom-right-radius: 0;
+		}
+		
+		.example .hash.response {
+			border-top: 1px solid white;
+			border-top-left-radius: 0;
+			border-top-right-radius: 0;
+		}
+	</style>
+	<script type="text/javascript">
+		//<![CDATA[
+		
+			function setup_toc() {
+	 		  if ($('#content').length === 0) return;
+			  var _toc = $('<ol class="top"></ol>');
+			  var show = false;
+			  var toc = _toc;
+			  var counter = 0;
+			  var tags = ['h2', 'h3', 'h4', 'h5', 'h6'];
+			  var i;
+			  if ($('#content h1').length > 1) tags.unshift('h1');
+			  for (i = 0; i < tags.length; i++) { tags[i] = '#content ' + tags[i]; }
+			  var lastTag = parseInt(tags[0][1], 10);
+			  $(tags.join(', ')).each(function() {
+			    if (this.id == "content") return;
+			    show = true;
+			    var thisTag = parseInt(this.tagName[1], 10);
+			    if (this.id.length === 0) {
+			      var proposedId = $(this).text().replace(/[^a-z0-9-]/ig, '_');
+			      if ($('#' + proposedId).length > 0) { proposedId += counter; counter++; }
+			      this.id = proposedId;
+			    }
+			    if (thisTag > lastTag) { 
+			      for (i = 0; i < thisTag - lastTag; i++) { 
+			        var tmp = $('<ol/>'); toc.append(tmp); toc = tmp; 
+			      } 
+			    }
+			    if (thisTag < lastTag) { 
+			      for (i = 0; i < lastTag - thisTag; i++) toc = toc.parent(); 
+			    }
+			    toc.append('<li><a href="#' + this.id + '">' + $(this).text() + '</a></li>');
+			    lastTag = thisTag;
+			  });
+			  if (!show) return;
+			  html = '<div id="toc"><p class="title"><a class="hide_toc" href="#"><strong>Table of Contents</strong></a> <small>(<a href="#" class="float_toc">left</a>)</small></p></div>';
+			  $('#content').prepend(html);
+			  $('#toc').append(_toc);
+			  $('#toc .hide_toc').toggle(function() { 
+			    $('#toc .top').slideUp('fast');
+			    $('#toc').toggleClass('hidden');
+			    $('#toc .title small').toggle();
+			  }, function() {
+			    $('#toc .top').slideDown('fast');
+			    $('#toc').toggleClass('hidden');
+			    $('#toc .title small').toggle();
+			  });
+			  $('#toc .float_toc').toggle(function() { 
+			    $(this).text('float');
+			    $('#toc').toggleClass('nofloat');
+			  }, function() {
+			    $(this).text('left');
+			    $('#toc').toggleClass('nofloat');
+			  });
+			}
+			$(document).ready(setup_toc);
+		//]]>
+	</script>
+  </head>
+  <body>
+    <script type="text/javascript" charset="utf-8">
+      if (window.top.frames.main) document.body.className = 'frames';
+    </script>
+    
+    <div id="header">
+      <%= erb(:search) %>
+    </div>
+    
+    <iframe id="search_frame"></iframe>
+    
+    <div id="content" style="padding-top: 12px;">
+		<%= yieldall %>
+	</div>
+    
+    <%= erb(:footer) %>
+  </body>
+</html>

data/templates/rest/layout/html/search.erb

@@ -0,0 +1,4 @@
+<div id="search">
+  <!-- <a id="topic_list_link" href="#">Topic List</a> -->
+  <a id="resource_list_link" href="#">Resources</a>
+</div>

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

@@ -0,0 +1,29 @@
+include Helpers::FilterHelper
+
+def init
+  @page_title = options[:title]
+  if object == "_index.html"
+    
+  elsif object.name == :root
+    sections :layout, [:index]
+  else
+    super
+  end
+end
+
+def javascripts
+  super + %w(js/rest_plugin.js)
+end
+
+def menu_lists
+  [ { :type => 'resource', :title => "Resources", :search_title => "List of Resources" },
+    { :type => 'topic', :title => "Topics", :search_title => "Topic List" },
+    { :type => 'file', :title => "Files", :search_title => "File List" } ]
+end
+
+def index
+  path_to_readme = (options[:readme]) ? options[:readme] : "./doc/README_FOR_API"
+  @readme = YARD::CodeObjects::ExtraFileObject.new(path_to_readme) if File.exists?(path_to_readme)
+  @resources = index_objects(@objects)
+  erb(:index)
+end

data/templates/rest/method_details/html/header.erb

@@ -0,0 +1,3 @@
+<div class="method_details <%= @index == 0 ? 'first' : '' %>">
+  <%= yieldall %>
+</div>

data/templates/rest/method_details/html/method_url.erb

@@ -0,0 +1,8 @@
+<% if object.tags(:url).size > 0 %>
+<h3>Url:</h3>
+<ul id="<%= anchor_for(object) %>">  
+  <% object.tags(:url).each do |url| %>
+  <li><%= url.text %></li>
+  <% end %>
+</ul>
+<% end %>

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

@@ -0,0 +1,7 @@
+def init
+  sections :header, [:method_signature, :method_url, T('docstring')]
+end
+
+def header
+  erb(:header)
+end

data/templates/rest/tags/html/example_request.erb

@@ -0,0 +1,9 @@
+<% if object.has_tag?(:example_request) %>
+  <div class="examples">
+    <h3>Example Request:</h3>
+    <% object.tags(:example_request).each do |tag| %>
+      <h4><%= htmlify_line(tag.name) %></h4>
+      <pre class="example code"><%= html_syntax_highlight(tag.text, :plain) %></pre>
+    <% end %>
+  </div>
+<% end %>

data/templates/rest/tags/html/example_response.erb

@@ -0,0 +1,9 @@
+<% if object.has_tag?(:example_response) %>
+  <div class="examples">
+    <h3>Example Response:</h3>
+    <% object.tags(:example_response).each do |tag| %>
+      <h4><%= htmlify_line(tag.name) %></h4>
+      <pre class="example code"><%= html_syntax_highlight(tag.text, :plain) %></pre>
+    <% end %>
+  </div>
+<% end %>

data/templates/rest/tags/html/generic_tag.erb

@@ -0,0 +1,17 @@
+<h3><%= @label ? @label : YARD::Tags::Library.labels[@name] %>:</h3>
+<ul class="<%= @name %>">
+  <% object.tags(@name).each do |tag| %>
+    <li>
+      <% unless @no_types %>
+        <span class='type'><%= format_types(tag.types) %></span>
+      <% end %>
+      <% unless @no_names %>
+        <span class='name'><%= h tag.name %></span>
+      <% end %>
+      <% if tag.text && !tag.text.empty? %>
+        <% unless (@no_types || tag.types.nil? || tag.types.empty?) && @no_names %>&mdash;<% end %>
+        <%= htmlify_line(tag.text) %>
+      <% end %>
+    </li>
+  <% end %>
+</ul>

data/templates/rest/tags/html/index.erb

@@ -0,0 +1,3 @@
+<div class="tags">
+  <%= yieldall %>
+</div>

data/templates/rest/tags/html/key_for.erb

@@ -0,0 +1,20 @@
+<% if object.has_tag?(:key_for) %>
+  <% object.tags(:key_for).group_by{|tag| tag.name }.each_pair do |hash_name, tags| %>
+    <h3>Keys for Hash (<tt><%= hash_name %></tt>):</h3>
+    <ul>
+    <% tags.each do |tag| %>
+      <li>
+        <span class="name"><%= tag.pair.name %></span>
+        <span class="type"><%= format_types(tag.pair.types) || ['Object'] %></span>
+        <span class="default">
+          <% if tag.pair.defaults %>
+            &mdash; default:
+          <%= tag.pair.defaults.map {|t| "<tt>#{h t}</tt>" }.join(", ") %>
+          <% end %>
+        </span>
+        <%= htmlify_line(tag.pair.text) if tag.pair.text %>
+      </li>
+    <% end %>
+    </ul>
+  <% end %>
+<% end %>

data/templates/rest/tags/html/value_for.erb

@@ -0,0 +1,13 @@
+<% if object.has_tag?(:value_for) %>
+  <% object.tags(:value_for).group_by{|tag| tag.name }.each_pair do |argument_name, tags| %>
+    <h3>Valid values for (<tt><%= argument_name %></tt>):</h3>
+    <ul>
+    <% tags.each do |tag| %>
+      <li>
+        <span class="name"><%= tag.pair.name %></span>
+        <%= htmlify_line(tag.pair.text) if tag.pair.text %>
+      </li>
+    <% end %>
+    </ul>
+  <% end %>
+<% end %>

data/templates/rest/tags/setup.rb

@@ -0,0 +1,47 @@
+def init
+  super
+  sections.push(:index,[:argument,
+                        :optional_argument,
+                        :key_for,
+                        :value_for,
+                        :example_request,
+                        :request_field,
+                        :example_response,
+                        :response_field,
+                        :header,
+                        :response_code])
+end
+
+def request_field
+  generic_tag :request_field
+end
+
+def response_field
+  generic_tag :response_field
+end
+
+def argument
+  generic_tag :argument, :no_types => false
+end
+
+def optional_argument
+  generic_tag :optional_argument, :no_types => false
+end
+
+def header
+  generic_tag :header
+end
+
+def response_code
+  generic_tag :response_code
+end
+
+def generic_tag(name, opts = {})
+  return unless object.has_tag?(name)
+  @no_names = true if opts[:no_names]
+  @no_types = true if opts[:no_types]
+  @name = name
+  out = erb('generic_tag')
+  @no_names, @no_types = nil, nil
+  out
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-rest
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -40,9 +40,34 @@ extra_rdoc_files:
 files:
 - Rakefile
 - example/app/controllers/examples_controller.rb
+- example/doc/README_FOR_API
 - lib/yard-rest.rb
 - lib/yard-rest/rest_filters.rb
 - lib/yard-rest/tags.rb
+- templates/rest/class/html/header.erb
+- templates/rest/class/html/method_details_list.erb
+- templates/rest/class/html/setup.rb
+- templates/rest/docstring/html/setup.rb
+- templates/rest/docstring/html/text.erb
+- templates/rest/fulldoc/html/full_list_resource.erb
+- templates/rest/fulldoc/html/full_list_topic.erb
+- templates/rest/fulldoc/html/js/rest_plugin.js
+- templates/rest/fulldoc/html/setup.rb
+- templates/rest/layout/html/footer.erb
+- templates/rest/layout/html/index.erb
+- templates/rest/layout/html/layout.erb
+- templates/rest/layout/html/search.erb
+- templates/rest/layout/html/setup.rb
+- templates/rest/method_details/html/header.erb
+- templates/rest/method_details/html/method_url.erb
+- templates/rest/method_details/html/setup.rb
+- templates/rest/tags/html/example_request.erb
+- templates/rest/tags/html/example_response.erb
+- templates/rest/tags/html/generic_tag.erb
+- templates/rest/tags/html/index.erb
+- templates/rest/tags/html/key_for.erb
+- templates/rest/tags/html/value_for.erb
+- templates/rest/tags/setup.rb
 - README.markdown
 - VERSION
 homepage: https://github.com/spape/yard-rest-plugin