yard-restful 1.2.1 → 1.2.2

data/README.markdown

@@ -1,22 +1,24 @@
 # Yardoc RESTful Web Service Plugin
 
-Previous authors: [vWorkApp](http://www.vworkapp.com), [rknLA](http://github.com/rknLA), [lsegal](http://gnuu.org/), [spape](http://github.com/spape), [DerNalia](http://github.com/DerNalia)
-
 A plugin for [Yardoc](http://yardoc.org/) that generates documentation for RESTful web services.
 
+Previous authors: [vWorkApp](http://www.vworkapp.com), [rknLA](http://github.com/rknLA), [lsegal](http://gnuu.org/), [spape](http://github.com/spape), [DerNalia](http://github.com/DerNalia)
+
 ## Install
-Bundler will reduce your headaches, so, please you that
+Bundler will reduce your headaches:
+
 	gem 'yard-restful' # in your gemfile
 
 You may need to include the following dependencies as well:
+
 	gem 'redcarpet'
 	gem 'yard'
 
 It also requires the Jeweler gem if you plan to use the rake build tasks.
 
 You'll probably want to add these to your .gitignore as well
-	/.yardoc/*/*
-	/.yardoc/*
+
+	/.yardoc
 	/public/api
 
 So you'll have to re-genenarte your API on every machine. This should encourage more up to dateness
@@ -36,36 +38,48 @@ So that way, whenever you want to generate your API docs, you simply need to run
 	bundle exec yardoc
 
 
-## See an API-Example
+## Samples
 
-[Sample application](http://kraft001.github.com/yard-restful-sample)
+[Full rails 3 application](http://github.com/kraft001/yard-restful-sample) with [documentation](http://kraft001.github.com/yard-restful-sample/index.html)
+
+[Example documentation](http://kraft001.github.com/yard-restful/index.html), also [with frames](http://kraft001.github.com/yard-restful/frames.html)
+
+[Sample controller](http://github.com/kraft001/yard-restful/blob/master/example/books_controller.rb) and [sample model](http://github.com/kraft001/yard-restful/blob/master/example/book.rb)
 
 ## Writing Comments
 
 The following tags are provided:
 
 - **@restful_api** version
+
   Specifies the resource (controller) or object (model). This tag is compulsory, only **classes** and **methods** that include this in their comments are included in the API documentation.
 
 - **@url** url
+
   Specifies the URL which someone should use to access that resource.
 
 - **@action** action
+
   Specifies the http action (GET, POST, PUT etc.).
 
 - **@required** [type] name description
+
   Specifies an argument that must be passed to the service. You can specify as many of these as you need.
 
 - **@optional** [type] name description
+
   Specifies an optional argument that may be passed to the service. You can specify as many of these as you need.
 
 - **@response** [type] description
+
   Specifies type of the response. Usually just a link to an object.
 
 - **@response_field** [type] name description
+
   Further specifies the fields that are returned within the response.
 
 - **@property** [type] name description
+
   A property (attribute) of an object.
 
 ### Examples
@@ -75,42 +89,37 @@ Examples should always be together in the following order: example_request, exam
 Markdown rendering for the text is activated if a tags text contains a newline (see example).
 
 - **@example_request**
+
   An example of the request that is send to the service.
 
 - **@example_request_description**
+
   The description text for the example request.
 
 - **@example_response**
+
   An example of the response that is returned from the service.
 
 - **@example_response_description**
+
   The description text for the example response.
 
 - **@example**
+
   Example of an object.
 
-  @example_response example.
-    ```json
-    {
-      "examples": [{
-        "id":1,
-        "title":"Animals",
-        "text":"Dogs and cats are some.",
-        "highlight":true
-       }]
-    }
-    ```
 ## Ignored Documentation
 
 This plugin only documents **classes** and **methods** with **@restful_api** tag. It does not support module documentation.
 
-## Example:
-
-[Sample controller](http://kraft001.github.com/yard-restful-sample/app/controllers/books_controller.rb) and [sample model](http://kraft001.github.com/yard-restful-sample/app/models/book.rb)
-
 ## Development
 
 As always, you can see what tasks are available by running:
 
     rake -T
 
+You can run the template locally over the included sample code by using the following rake tasks:
+
+    rake example:generate
+    rake example:clean
+

data/Rakefile

@@ -21,10 +21,25 @@ end
 
 desc "Rebuild the gem from the gemspec"
 task :rebuild do
-  gemfilename = 'yard-restful-' + File.open('VERSION').gets.strip + '.gem'
+  gemfilename = 'yard-restful-' + IO.read('VERSION').strip + '.gem'
   `rm yard-restful-*.gem`
-  `gem uninstall yard-restful&& \
+  `gem uninstall yard-restful && \
    gem build yard-restful.gemspec && \
    gem install #{gemfilename}`
 end
 
+namespace :example do
+  desc "Generate example docs"
+  task :generate do
+    puts `yardoc -e ./lib/yard-restful.rb --title "Example Books API" --readme ./example/API_README.md --markup markdown ./example/*.rb`
+    # `x-www-browser ./doc/index.html`
+    puts 'On success open ./doc/index.html or ./doc/frames.html in your preferred browser'
+  end
+
+  desc "Clean example docs"
+  task :clean do
+    `rm -R doc`
+    `rm -R .yardoc`
+    puts 'Done!'
+  end
+end

data/VERSION

@@ -1 +1 @@
-1.2.1
+1.2.2

data/lib/{yard-rest.rb → yard-restful.rb}

@@ -1,8 +1,8 @@
 YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + '/../templates'
 
-require 'yard-rest/tags'
-require 'yard-rest/rest_filters'
-require 'yard-rest/html_blocks_helper'
+require 'yard-restful/tags'
+require 'yard-restful/rest_filters'
+require 'yard-restful/html_blocks_helper'
 
 YARD::Templates::Template.extra_includes << RestFilters
 YARD::Templates::Template.extra_includes << ->(opts) { HtmlBlocksHelper if opts.format == :html }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-restful
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.2.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-23 00:00:00.000000000 Z
+date: 2012-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -37,10 +37,10 @@ extra_rdoc_files:
 - VERSION
 files:
 - Rakefile
-- lib/yard-rest.rb
-- lib/yard-rest/html_blocks_helper.rb
-- lib/yard-rest/rest_filters.rb
-- lib/yard-rest/tags.rb
+- lib/yard-restful.rb
+- lib/yard-restful/html_blocks_helper.rb
+- lib/yard-restful/rest_filters.rb
+- lib/yard-restful/tags.rb
 - templates/default/class/html/fields_list.erb
 - templates/default/class/html/header.erb
 - templates/default/class/html/object_details.erb
@@ -85,3 +85,4 @@ signing_key:
 specification_version: 3
 summary: Yardoc plugin for Restful web services
 test_files: []
+has_rdoc: