yard-rest-plugin 0.1.5 → 0.2.0

data/README.markdown

@@ -1,27 +1,27 @@
-Yardoc RESTful Web Service Plugin
-=================================
+# Yardoc RESTful Web Service Plugin
+
 by VisFleet
 
 A plugin for [Yardoc](http://yardoc.org/) that generates documentation for RESTful web services. 
 
-Install
--------
+## Install
     sudo gem install yard-rest-plugin
 
 It also requires the Jeweler gem if you plan to use the rake build tasks.
 
-Generating Docs
----------------
+## Generating Docs
+
 When using yardoc you ask it to use the "rest" template (the -t option). For example: 
 
     yardoc '*.rb' -t rest --title "Our App's API"
 
-Writing Comments
-----------------
+## Writing Comments
+
 In addition to starting your comment with the normal RDoc description. The following tags are provided:
 
-- @url url. Specifies the URL that the service is accessed from. This tag is compulsory, only classes and methods 
-    that include this in their comments are included
+- @url url. Specifies the URL that the service is accessed from. This tag is compulsory, only **classes** and **methods** that include this in their comments are included.
+
+- @topic topic. Specifies the topic to categorise a **class** (not a method) under.
 
 - @argument [type] name description. Specifies an argument that is passed to the service. You can specify as 
     many of these as required
@@ -30,7 +30,13 @@ In addition to starting your comment with the normal RDoc description. The follo
 
 - @response_field name description. Further specifies the fields that are returned within the response
 
-For example:
+## Ignored Documentation
+
+This plugin only documents **classes** and **methods** with **@url** tags. It does not support module documentation.
+
+The rationale here is that you are documenting external services (as represented by controllers and methods), and not internal code.
+
+## Example:
 
     ##
     # Retuns all samples, as XML, for the current user that match the given parameters.
@@ -68,8 +74,8 @@ For example:
     def index
     end
 
-Development
------------
+## Development
+
 You can run the template locally over the included sample code by using the following rake tasks:
     
     rake ex:clean

data/VERSION

@@ -1 +1 @@
-0.1.5
+0.2.0

data/example/SampleController.rb

@@ -1,6 +1,7 @@
 ##
 # The Sample sevices let you list, create, update, and delete Samples from our application.
 # @url /sample
+# @topic Sample
 #
 class SampleController
 

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

@@ -1,8 +1,24 @@
 <div class="service">
   <h1><span class="minor_heading">Resource: </span><%= object.tag("url").text %></h1>
-  <% unless object.tag("topic").nil? %>
-  <!-- fixme: needs style -->
-    <h1><span class="minor_heading">Topic: </span><%= object.tag("topic").text %></h1>
+  <% unless object.tags("topic").empty? %>
+    <h3>Topics:</h3> 
+    <ul class="box">
+      <% object.tags("topic").each do |topic| %>
+        <li><%= topic.text %></li>
+      <% end %>
+    </ul>
   <% end %>
   <%= yieldall %>
 </div>
+
+
+
+
+  
+  
+    
+  
+    
+  
+  
+  

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

@@ -222,4 +222,14 @@ h1 .note.title {
   text-transform: capitalize; 
 }
 
+ul.box {
+  font-size: 1em;
+  height: 1em;
+}
 
+ul.box li {
+  float: left;
+  display: block;
+  text-align: left;
+  padding-right: 10px;
+}

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

@@ -0,0 +1,8 @@
+<li><a href="<%= url_for('_index.html') %>">Index</a></li>
+<% n = 1 %>
+<% @items.sort_by {|s| s.name.to_s }.each do |resource| %>
+<% unless resource.tags("url").first.nil? %>
+  <li class="r<%= n %>"><%= linkify(resource, resource.tags("url").first.text) %></li>
+<% end %>
+<% n = n == 2 ? 1 : 2 %>
+<% end %>

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

@@ -0,0 +1,12 @@
+<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| %>
+      <li class="r<%= n %>"><%= linkify(object, object.tag("url").text) %></li>
+    <% end%>
+  <% end %>
+  <% n = n == 2 ? 1 : 2 %>
+<% end %>
+

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

@@ -4,10 +4,13 @@ function fixBoxInfoHeights() {
        $(this).prev().height($(this).height()); 
     });
 }
-
 function searchFrameLinks() {
-  $('#service_list_link').click(function() {
-    toggleSearchFrame(this, relpath + 'service_list.html');
+  $('#topic_list_link').click(function() {
+    toggleSearchFrame(this, relpath + 'topic_list.html');
+  });
+
+  $('#resource_list_link').click(function() {
+    toggleSearchFrame(this, relpath + 'resource_list.html');
   });
 
   $('#file_list_link').click(function() {

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

@@ -7,6 +7,11 @@ function fullListSearch() {
         var link = $(this).children('a:last');
         link.text(link.text()); 
       });
+      if (clicked) {
+        clicked.parents('ul').each(function() {
+          $(this).removeClass('collapsed').prev().removeClass('collapsed');
+        });
+      }
       highlight();
     }
     else {
@@ -40,6 +45,50 @@ function fullListSearch() {
   $('#full_list').after("<div id='noresults'>No results were found.</div>")
 }
 
+clicked = null;
+function linkList() {
+  $('#full_list li, #full_list li a:last').click(function(evt) {
+    if ($(this).hasClass('toggle')) return true;
+    if (this.tagName.toLowerCase() == "li") {
+      var toggle = $(this).children('a.toggle');
+      if (toggle.size() > 0 && evt.pageX < toggle.offset().left) {
+        toggle.click();
+        return false;
+      }
+    }
+    if (clicked) clicked.removeClass('clicked');
+    var win = window.parent;
+    if (window.top.frames.main) {
+      win = window.top.frames.main;
+      var title = $('html head title', win.document).text();
+      $('html head title', window.parent.document).text(title);
+    }
+    if (this.tagName.toLowerCase() == "a") {
+      clicked = $(this).parent('li').addClass('clicked');
+      win.location = this.href;
+    }
+    else {
+      clicked = $(this).addClass('clicked');
+      win.location = $(this).find('a:last').attr('href');
+    }
+    return false;
+  });
+}
+
+function collapse() {
+  if (!$('#full_list').hasClass('class')) return;
+  $('#full_list.class a.toggle').click(function() { 
+    $(this).parent().toggleClass('collapsed').next().toggleClass('collapsed');
+    highlight();
+    return false; 
+  });
+  $('#full_list.class ul').each(function() {
+    $(this).addClass('collapsed').prev().addClass('collapsed');
+  });
+  $('#full_list.class').children().removeClass('collapsed');
+  highlight();
+}
+
 function highlight(no_padding) {
   var n = 1;
   $('#full_list li:visible').each(function() {
@@ -52,4 +101,17 @@ function highlight(no_padding) {
   });
 }
 
+function escapeShortcut() {
+  $(document).keydown(function(evt) {
+    if (evt.which == 27) {
+      $('#search_frame', window.top.document).slideUp(100);
+      $('#search a', window.top.document).removeClass('active inactive')
+      $(window.top).focus();
+    }
+  });
+}
+
+$(escapeShortcut);
 $(fullListSearch);
+$(linkList);
+$(collapse);

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

@@ -1,10 +1,8 @@
 include Helpers::ModuleHelper
-
+include Helpers::FilterHelper
 
 def init
-  pp "--1--", options[:objects]
   options[:objects] = objects = run_verifier(options[:objects])
-  pp "--2--", options[:objects]
   options[:files] = ([options[:readme]] + options[:files]).compact.map {|t| t.to_s }
   options[:readme] = options[:files].first
   options[:title] ||= "Documentation by YARD #{YARD::VERSION}"
@@ -69,15 +67,30 @@ def generate_assets
   end
   
   @object = Registry.root
-  generate_service_list
+  generate_resource_list
+  generate_topic_list
   generate_file_list
 end
 
-def generate_service_list
+def generate_topic_list
+  topic_objects = options[:objects].reject {|o| o.root? || !is_class?(o) || o.tags('url').empty? || o.tags('topic').empty? }
+  @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 = options[:objects]
-  @list_title = "Service List"
-  @list_type = "service"
-  asset('service_list.html', erb(:full_list))
+  @list_title = "Resource List"
+  @list_type = "resource"
+  asset('resource_list.html', erb(:full_list))
 end
 
 def generate_file_list

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

@@ -18,18 +18,18 @@
   <table>
     <tr>
       <td valign='top' width="33%">
-        <% @objects_by_letter.sort_by {|l,o| l.to_s }.each do |letter, objects| %>
+        <% @topics.sort_by {|t,o| t.to_s }.each do |topic, objects| %>
           <% if (i += 1) % 8 == 0 %>
             </td><td valign='top' width="33%">
             <% i = 0 %>
           <% end %>
-          <ul id="alpha_<%= letter %>" class="alpha">
-            <li class="letter"><%= letter %></li>
+          <ul id="alpha_<%= topic %>" class="alpha">
+            <li class="letter"><%= topic %></li>
             <ul>
               <% objects.each do |obj| %>
-                <% unless obj.tags("topic").first.nil? %>
+                <% unless obj.tags("url").first.nil? %>
                   <li>
-                    <%= linkify(obj, obj.tags("topic").first.text) %> 
+                    <%= linkify(obj, obj.tags("url").first.text) %> 
                   </li>
                 <% end %>
               <% end %>
@@ -40,4 +40,16 @@
     </tr>
   </table>
 
+
+  <h2>Resources A-Z</h2>
+  <ul>
+  <% @objects.each do |object| %>
+    <% unless object.tags("url").first.nil? %>
+      <li>
+        <%= linkify(object, object.tags("url").first.text) %> 
+      </li>
+    <% end %>
+  <% end %>
+  </ul>
+
 </div>

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

@@ -1,4 +1,5 @@
 <div id="search">
-  <a id="service_list_link" href="#">Service List</a>
-  <a id ="file_list_link" href="#">File List</a>
+  <a id="topic_list_link" href="#">Topic List</a>
+  <a id="resource_list_link" href="#">Resource List</a>
+  <a id="file_list_link" href="#">File List</a>
 </div>

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

@@ -1,3 +1,5 @@
+include Helpers::FilterHelper
+
 def init
   @breadcrumb = []
 
@@ -25,9 +27,17 @@ def contents
 end
 
 def index
-  @objects_by_letter = {}
-  objects = @objects.reject {|o| o.root? || o.tags('topic').empty? }.sort_by {|o| o.tags('topic').first.text }
-  objects.each {|o| (@objects_by_letter[o.tags('topic').first.text[0,1].upcase] ||= []) << o }
+
+  legitimate_objects = @objects.reject {|o| o.root? || !is_class?(o) || o.tags('url').empty?}
+  topic_objects = legitimate_objects.reject{|o| o.tags('topic').empty? }
+  @topics = {}
+  
+  topic_objects.each do |object|
+    object.tags('topic').each { |topic| (@topics[topic.text] ||= []) << object }
+  end
+
+  @resources = legitimate_objects.sort_by {|o| o.tags('url').first.text }
+  
   erb(:index)
 end
 

data/yard-rest-plugin.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{yard-rest-plugin}
-  s.version = "0.1.5"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Aisha Fenton"]
@@ -24,6 +24,7 @@ Gem::Specification.new do |s|
      "lib/yard-rest-plugin.rb",
      "lib/yard-rest-plugin/base_helper.rb",
      "pkg/yard-rest-plugin-0.1.5.gem",
+     "pkg/yard-rest-plugin-0.2.0.gem",
      "templates/rest/.DS_Store",
      "templates/rest/class/html/header.erb",
      "templates/rest/class/html/method_details_list.erb",
@@ -37,7 +38,8 @@ Gem::Specification.new do |s|
      "templates/rest/fulldoc/html/css/style.css",
      "templates/rest/fulldoc/html/full_list.erb",
      "templates/rest/fulldoc/html/full_list_files.erb",
-     "templates/rest/fulldoc/html/full_list_service.erb",
+     "templates/rest/fulldoc/html/full_list_resource.erb",
+     "templates/rest/fulldoc/html/full_list_topic.erb",
      "templates/rest/fulldoc/html/js/app.js",
      "templates/rest/fulldoc/html/js/full_list.js",
      "templates/rest/fulldoc/html/js/jquery.js",

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 5
-  version: 0.1.5
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Aisha Fenton
@@ -47,6 +47,7 @@ files:
 - lib/yard-rest-plugin.rb
 - lib/yard-rest-plugin/base_helper.rb
 - pkg/yard-rest-plugin-0.1.5.gem
+- pkg/yard-rest-plugin-0.2.0.gem
 - templates/rest/.DS_Store
 - templates/rest/class/html/header.erb
 - templates/rest/class/html/method_details_list.erb
@@ -60,7 +61,8 @@ files:
 - templates/rest/fulldoc/html/css/style.css
 - templates/rest/fulldoc/html/full_list.erb
 - templates/rest/fulldoc/html/full_list_files.erb
-- templates/rest/fulldoc/html/full_list_service.erb
+- templates/rest/fulldoc/html/full_list_resource.erb
+- templates/rest/fulldoc/html/full_list_topic.erb
 - templates/rest/fulldoc/html/js/app.js
 - templates/rest/fulldoc/html/js/full_list.js
 - templates/rest/fulldoc/html/js/jquery.js

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

@@ -1,8 +0,0 @@
-<li><a href="<%= url_for('_index.html') %>">/</a></li>
-<% n = 1 %>
-<% @items.sort_by {|s| s.name.to_s }.each do |service| %>
-<% unless service.tags("topic").first.nil? %>
-  <li class="r<%= n %>"><%= linkify(service, service.tags("topic").first.text) %></li>
-<% end %>
-<% n = n == 2 ? 1 : 2 %>
-<% end %>