yard-rest 1.0.5 → 1.1.0

data/README.markdown

@@ -2,7 +2,7 @@
 
 originally by [vWorkApp](http://www.vworkapp.com)
 rewritten for 0.3.0 by [rknLA](http://github.com/rknLA) with substantial help from [lsegal](http://gnuu.org/)
-customized by [spape](http://github.com/spape) for the [MAdeK](http://github.com/zhdk/madek) API-Documentation
+customized by [spape](http://github.com/spape) for the [MAdeK](http://github.com/zhdk/madek) [API-Documentation](http://medienarchiv.zhdk.ch/api)
 
 A plugin for [Yardoc](http://yardoc.org/) that generates documentation for RESTful web services. 
 
@@ -11,6 +11,10 @@ A plugin for [Yardoc](http://yardoc.org/) that generates documentation for RESTf
 
 It also requires the Jeweler gem if you plan to use the rake build tasks.
 
+## Fast Example
+
+Run 'rake ex:generate' inside this plugin folder and get a look to the generated doc/index.html.
+
 ## Demo
 
 Visit [MAdeK-Api-Documetnation](http://medienarchiv.zhdk.ch/api) for a demonstration. Or visit ROR project [MAdeK](http://github.com/zhdk/madek) on github to see how we document our api.
@@ -36,7 +40,7 @@ You may also include yard-rest in your gemfile using:
 You may need to include the following dependencies as well:
 
     gem 'redcarpet'
-    gem 'yard', '~>0.7.4'
+    gem 'yard', '~>0.8.1'
 
 If you include yard-rest in your gemfile, you should generate docs using bundle exec:
 
@@ -60,14 +64,27 @@ In addition to starting your comment with the normal RDoc description. The follo
 
 Examples should always be together in the following order: example_request, example_request_description, example_response, example_response_description (as soon as you write a example_request you need a following example_response and the other way around).
 
+Markdown rendering for the text is activated if a tags text contains a newline (see example).
+
 - @example_request example. An example of the request that is send to the service.
 
 - @example_request_description description. The description text for the example request.
 
 - @example_response example. An example of the response that is returned from the service.
 
-- @example_response_description example. The description text for the example response.
+- @example_response example.
+    ```json
+    {
+      "examples": [{
+        "id":1,
+        "title":"Animals",
+        "text":"Dogs and cats are some.",
+        "highlight":true
+       }]
+    }
+    ```
 
+- @example_response_description example. The description text for the example response.
 
 ## Ignored Documentation
 
@@ -84,7 +101,7 @@ Both controller *and* methods must have @resource tags to be included in documen
   # it's a good example of how European action can produce results | some of these carpets are among the finest examples of the period.
   #
   class ExamplesController
-
+  
     ##
     # Get a collection of examples:
     # 
@@ -107,13 +124,23 @@ Both controller *and* methods must have @resource tags to be included in documen
     # 
     # @example_request {"highlight": true}
     # @example_request_description Request only highlighted examples.
-    # @example_response {"examples": [{"id":1, "title":"Animals", "text":"Dogs and cats are some.", "highlight":true}]}
+    # @example_response 
+    #   ```json
+    #   {
+    #     "examples": [{
+    #       "id":1,
+    #       "title":"Animals",
+    #       "text":"Dogs and cats are some.",
+    #       "highlight":true
+    #     }]
+    #   }
+    #   ```
     # @example_response_description Responds only with highlighted examples.
     #
     def index
       #...
     end
-
+  
     ##
     # Get a collection of examples:
     # 
@@ -130,13 +157,23 @@ Both controller *and* methods must have @resource tags to be included in documen
     #
     # @example_request {"id":1}
     # @example_request_description Just requests the example with id 1. 
-    # @example_response {"example": {"id":1, "title":"Animals", "text":"Dogs and cats are some.", "highlight":true}}
+    # @example_response 
+    #   ```json
+    #   {
+    #     "example": {
+    #       "id":1,
+    #       "title":"Animals",
+    #       "text":"Dogs and cats are some.",
+    #       "highlight":true
+    #     }
+    #   }
+    #   ```
     # @example_response_description Responds with the requested example.
     #
     def show
       #...
     end
-
+  
     ##
     # Create an example:
     # 

data/Rakefile

@@ -10,7 +10,7 @@ begin
     gem.email = ''
     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.add_dependency("yard", '~>0.8.1')
     gem.files = Dir.glob("{lib,example,templates}/**/*").concat(["Rakefile"])
     gem.extra_rdoc_files = ['VERSION', 'README.markdown']
   end
@@ -31,7 +31,7 @@ end
 namespace :ex do
   desc "Generate example docs"
   task :generate do
-    `yardoc 'example/*.rb' --backtrace -e ./lib/yard-rest.rb -r example/README.markdown --title 'Sample API'`
+    `yardoc 'example/app/controllers/examples_controller.rb' -e ./lib/yard-rest.rb --title "Our App's API" --readme "example/doc/README_FOR_API"`
   end
 
   desc "Clean example docs"

data/VERSION

@@ -1 +1 @@
-1.0.5
+1.1.0

data/example/app/controllers/examples_controller.rb

@@ -26,7 +26,17 @@ class ExamplesController
   # 
   # @example_request {"highlight": true}
   # @example_request_description Request only highlighted examples.
-  # @example_response {"examples": [{"id":1, "title":"Animals", "text":"Dogs and cats are some.", "highlight":true}]}
+  # @example_response 
+  #   ```json
+  #   {
+  #     "examples": [{
+  #       "id":1,
+  #       "title":"Animals",
+  #       "text":"Dogs and cats are some.",
+  #       "highlight":true
+  #     }]
+  #   }
+  #   ```
   # @example_response_description Responds only with highlighted examples.
   #
   def index
@@ -49,7 +59,17 @@ class ExamplesController
   #
   # @example_request {"id":1}
   # @example_request_description Just requests the example with id 1. 
-  # @example_response {"example": {"id":1, "title":"Animals", "text":"Dogs and cats are some.", "highlight":true}}
+  # @example_response 
+  #   ```json
+  #   {
+  #     "example": {
+  #       "id":1,
+  #       "title":"Animals",
+  #       "text":"Dogs and cats are some.",
+  #       "highlight":true
+  #     }
+  #   }
+  #   ```
   # @example_response_description Responds with the requested example.
   #
   def show

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

@@ -6,7 +6,7 @@
 			<h3 class="resource_url"><strong><%= meth.tag(:resource).text %></strong> [<%= meth.tag(:action).text %>]</h3>
 
 			<div class="parameters">	
-				<% if meth.tags(:required).size %>
+				<% if meth.tags(:required).size > 0 %>
 					<div class="required">
 						<h4>Required Parameters</h4>
 						<% meth.tags(:required).each do |required| %>
@@ -21,7 +21,7 @@
 					</div>
 				<% end %>
 
-				<% if meth.tags(:optional).size %>
+				<% if meth.tags(:optional).size > 0 %>
 					<div class="optional">
 						<h4>Optional Parameters</h4>
 						<% meth.tags(:optional).each do |optional| %>
@@ -37,7 +37,7 @@
 				<% end %>
 			</div><!-- parameters -->
 			
-			<% if meth.tags(:response_field).size %>
+			<% if meth.tags(:response_field).size > 0 %>
 				<div class="response_fields">
 					<h4>Response Fields</h4>
 					<% meth.tags(:response_field).each do |response_field| %>
@@ -52,7 +52,7 @@
 				</div>
 			<% end %>
 			
-			<% if meth.tags(:example_request).size %>
+			<% if meth.tags(:example_request).size > 0 %>
 				<div class="examples">
 					<h4>Examples</h4>
 					<% meth.tags(:example_request).each_with_index do |example_request, i| %>
@@ -60,16 +60,44 @@
 							<% 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="description">
+								<% if example_request_description %>
+									<% if example_request_description.text =~ /\n/im %>
+										<%= htmlify(example_request_description.text, :markdown) %>
+									<% else %>
+										<%= example_request_description.text %>
+									<% end %>
+								<% end %>
+							</span>
 							<span class="hash request">
 								<strong class="type">Request</strong>
-								<%= (example_request.nil?) ? "" : example_request.text %>
+								<% if example_request %>
+									<% if example_request.text =~ /\n/im %>
+										<%= htmlify(example_request.text, :markdown) %>
+									<% else %>
+										<%= example_request.text %>
+									<% end %>
+								<% end %>
 							</span>
 							<span class="hash response">
 								<strong class="type">Response</strong>
-								<%= (example_response.nil?) ? "" : example_response.text %>
+								<% if example_response %>
+									<% if example_response.text =~ /\n/im %>
+										<%= htmlify(example_response.text, :markdown) %>
+									<% else %>
+										<%= example_response.text %>
+									<% end %>
+								<% end %>
+							</span>
+							<span class="description">
+								<% if example_response_description %>
+									<% if example_response_description.text =~ /\n/im %>
+										<%= htmlify(example_response_description.text, :markdown) %>
+									<% else %>
+										<%= example_response_description.text %>
+									<% end %>
+								<% end %>
 							</span>
-							<span class="description"><%= (example_response_description.nil?) ? "" : example_response_description.text %></span>
 						</div>
 					<% end %>
 				</div>

data/templates/default/layout/html/layout.erb

@@ -130,10 +130,38 @@
 			border-top-left-radius: 0;
 			border-top-right-radius: 0;
 		}
+		
+		pre {
+		  margin: 0;
+		}
+		
+		pre code {
+		  position: relative;
+		  border: 1px solid transparent;
+		  border-radius: 6px;
+		}
+		
+		pre code:hover {
+		  background: #d4e5fe;
+		}
+		
+		pre code:active {
+		  background: #c1d8fb;
+		}
 	</style>
 	<script type="text/javascript">
 		//<![CDATA[
 		
+		  function setup_log() {
+		    $("pre.code.json").attr("title", "click to inspect in browser debugger: console.log()");
+		    $("pre.code.json").css("cursor", "pointer");
+		    $("pre.code.json").click(function(){
+		      var code = $(this).find("code");
+		      console.log(code.html());
+		      console.log(JSON.parse(code.html()));
+		    });
+		  }
+		
 			function setup_toc() {
 	 		  if ($('#content').length === 0) return;
 			  var _toc = $('<ol class="top"></ol>');
@@ -186,7 +214,10 @@
 			    $('#toc').toggleClass('nofloat');
 			  });
 			}
-			$(document).ready(setup_toc);
+			$(document).ready(function(){
+			  setup_toc();
+			  setup_log();
+			});
 		//]]>
 	</script>
   </head>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-rest
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-30 00:00:00.000000000 Z
+date: 2012-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -20,7 +20,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.7.4
+        version: 0.8.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -28,7 +28,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.7.4
+        version: 0.8.1
 description: A customized plugin for Yardoc that produces API documentation for Restful
   web services
 email: ''