yard-rest 1.0.0

data/README.markdown

@@ -0,0 +1,165 @@
+# Yardoc RESTful Web Service Plugin
+
+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
+
+A plugin for [Yardoc](http://yardoc.org/) that generates documentation for RESTful web services. 
+
+## Install
+    sudo gem install yard-rest
+
+It also requires the Jeweler gem if you plan to use the rake build tasks.
+
+## Generating Docs
+
+When using yardoc you ask it to use the "rest" plugin (the --plugin option). For example: 
+
+    yardoc --plugin rest --title "Our App's API" --readme "./doc/README_FOR_API"
+
+## Gemfile functionality
+
+You may also include yard-rest in your gemfile using:
+
+    gem 'yard-rest'
+
+You may need to include the following dependencies as well:
+
+    gem 'redcarpet'
+    gem 'yard', '~>0.7.4'
+
+If you include yard-rest in your gemfile, you should generate docs using bundle exec:
+
+    bundle exec yardoc --plugin rest --title "Our App's API" --readme "./doc/README_FOR_API"
+
+## Writing Comments
+
+In addition to starting your comment with the normal RDoc description. The following tags are provided:
+
+- @resource resource. Specifies the resource (URL) that the service is accessed from. This tag is compulsory, only **classes** and **methods** that include this in their comments are included in the API documentation.
+
+- @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_field [type] name description. Further specifies the fields that are returned within the response.
+
+### Examples
+
+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).
+
+- @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.
+
+
+## Ignored Documentation
+
+This plugin only documents **classes** and **methods** with **@resource** 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.
+
+Both controller *and* methods must have @resource tags to be included in documentation.
+
+## Example:
+
+  ##
+  # A thing characteristic of its kind or illustrating a general rule: 
+  # 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:
+    # 
+    # @resource /examples
+    #
+    # @action GET
+    # 
+    # @optional [Boolean] highlight Show only highlighted examples.
+    #
+    # @response_field [Array] examples The collection of examples.  
+    # @response_field [Integer] examples[].id The id of that example.
+    # @response_field [String] examples[].title The title of that example.
+    # @response_field [String] examples[].text The text of that example.
+    # @response_field [String] examples[].highlight Information if the example is highlighted.
+    #
+    # @example_request {}
+    # @example_request_description Just requests an index of samples. 
+    # @example_response {"examples": [{"id":1, "title":"Animals", "text":"Dogs and cats are some.", "highlight":true}, {"id":2, "title":"Computers", "text":"Windows PC or Apple's Macintosh.", "highlight":false}]}
+    # @example_response_description Responds with the index of examples.
+    # 
+    # @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_description Responds only with highlighted examples.
+    #
+    def index
+      #...
+    end
+
+    ##
+    # Get a collection of examples:
+    # 
+    # @resource /examples/:id
+    #
+    # @action GET
+    # 
+    # @required [Integer] id The id of the example.
+    #
+    # @response_field [Integer] example.id The id of that example.
+    # @response_field [String] example.title The title of that example.
+    # @response_field [String] example.text The text of that example.
+    # @response_field [String] example.highlight Information if the example is highlighted.
+    #
+    # @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_description Responds with the requested example.
+    #
+    def show
+      #...
+    end
+
+    ##
+    # Create an example:
+    # 
+    # @resource /examples
+    #
+    # @action POST
+    # 
+    # @required [Hash] example The object of the new example.
+    # @required [String] example.title The title of the new example.
+    # @required [String] example.text The text of the new example.
+    #
+    # @optional [Boolean] example.highlight The highlight status of the new example. (Default is false)
+    #
+    # @example_request {"example": {"title":"Fish", "text": "Angel- or Butterflyfish"}}
+    # @example_resuest_description Create a new example for fish.
+    # @example_response {}
+    # @example_response_description Responds with an empty hash and status: 201 (Created).
+    #
+    def create
+      #...
+    end
+  end
+
+## 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 ex:clean
+    rake ex:generate
+
+
+

data/Rakefile

@@ -0,0 +1,42 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "yard-rest"
+    gem.summary = %Q{A customized 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. See README.markdown for more details}
+    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.files = Dir.glob("{lib,example,templates/rest}/**/*.*").concat(["Rakefile"])
+    gem.extra_rdoc_files = ['VERSION', 'README.markdown']
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+desc "Rebuild the gem from the gemspec"
+task :rebuild do
+  gemfilename = 'yard-rest-' + File.open('VERSION').gets.strip + '.gem'
+  `rm yard-rest-*.gem`
+  `gem uninstall yard-rest&& \
+   gem build yard-rest.gemspec && \
+   gem install #{gemfilename}`
+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'`
+  end
+
+  desc "Clean example docs"
+  task :clean do
+    `rm -R doc`
+    `rm -R .yardoc`
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/example/app/controllers/examples_controller.rb

@@ -0,0 +1,80 @@
+##
+# A thing characteristic of its kind or illustrating a general rule: 
+# 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:
+  # 
+  # @resource /examples
+  #
+  # @action GET
+  # 
+  # @optional [Boolean] highlight Show only highlighted examples.
+  #
+  # @response_field [Array] examples The collection of examples.  
+  # @response_field [Integer] examples[].id The id of that example.
+  # @response_field [String] examples[].title The title of that example.
+  # @response_field [String] examples[].text The text of that example.
+  # @response_field [String] examples[].highlight Information if the example is highlighted.
+  #
+  # @example_request {}
+  # @example_request_description Just requests an index of samples. 
+  # @example_response {"examples": [{"id":1, "title":"Animals", "text":"Dogs and cats are some.", "highlight":true}, {"id":2, "title":"Computers", "text":"Windows PC or Apple's Macintosh.", "highlight":false}]}
+  # @example_response_description Responds with the index of examples.
+  # 
+  # @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_description Responds only with highlighted examples.
+  #
+  def index
+    #...
+  end
+
+  ##
+  # Get a collection of examples:
+  # 
+  # @resource /examples/:id
+  #
+  # @action GET
+  # 
+  # @required [Integer] id The id of the example.
+  #
+  # @response_field [Integer] example.id The id of that example.
+  # @response_field [String] example.title The title of that example.
+  # @response_field [String] example.text The text of that example.
+  # @response_field [String] example.highlight Information if the example is highlighted.
+  #
+  # @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_description Responds with the requested example.
+  #
+  def show
+    #...
+  end
+
+  ##
+  # Create an example:
+  # 
+  # @resource /examples
+  #
+  # @action POST
+  # 
+  # @required [Hash] example The object of the new example.
+  # @required [String] example.title The title of the new example.
+  # @required [String] example.text The text of the new example.
+  #
+  # @optional [Boolean] example.highlight The highlight status of the new example. (Default is false)
+  #
+  # @example_request {"example": {"title":"Fish", "text": "Angel- or Butterflyfish"}}
+  # @example_resuest_description Create a new example for fish.
+  # @example_response {}
+  # @example_response_description Responds with an empty hash and status: 201 (Created).
+  #
+  def create
+    #...
+  end
+end

data/lib/yard-rest/rest_filters.rb

@@ -0,0 +1,21 @@
+module RestFilters
+
+  def index_objects(list)
+    list = reject_without_resource(list)
+    list
+  end
+
+  def reject_without_resource(list)
+    list.delete_if { |object| 
+      if [:class].include?(object.type)
+        object.meths.detect{|x| x.has_tag? :resource}.nil?
+      else 
+        true
+      end
+    }
+  end
+
+end
+
+
+

data/lib/yard-rest/tags.rb

@@ -0,0 +1,16 @@
+# Define custom tags
+YARD::Tags::Library.define_tag("URL for the Resource",          :resource)
+YARD::Tags::Library.define_tag("HTTP-Action for the Resource",  :action)
+
+YARD::Tags::Library.define_tag("Required Arguments",            :required,          :with_types_and_name)
+YARD::Tags::Library.define_tag("Optional Arguments",            :optional,          :with_types_and_name)
+
+YARD::Tags::Library.define_tag("Example Request",               :example_request)
+YARD::Tags::Library.define_tag("Example Request Description",   :example_request_description)
+YARD::Tags::Library.define_tag("Request Fields",                :request_field,     :with_types_and_name)
+
+YARD::Tags::Library.define_tag("Example Response",              :example_response)
+YARD::Tags::Library.define_tag("Example Response Description",  :example_response_description)
+YARD::Tags::Library.define_tag("Response Fields",               :response_field,    :with_types_and_name)
+
+YARD::Tags::Library.define_tag("Headers",                       :header, :with_name)

data/lib/yard-rest.rb

@@ -0,0 +1,6 @@
+YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + '/../templates'
+
+require File.join(File.dirname(__FILE__), 'yard-rest', 'tags')
+require File.join(File.dirname(__FILE__), 'yard-rest', 'rest_filters')
+
+YARD::Templates::Template.extra_includes << RestFilters

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: yard-rest
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- R. Kevin Nelson
+- Aisha Fenton
+- Sebastian Pape
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.7.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.7.4
+description: A plugin for Yardoc that produces API documentation for Restful web services.
+  See README.markdown for more details
+email: ''
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.markdown
+- VERSION
+files:
+- Rakefile
+- example/app/controllers/examples_controller.rb
+- lib/yard-rest.rb
+- lib/yard-rest/rest_filters.rb
+- lib/yard-rest/tags.rb
+- README.markdown
+- VERSION
+homepage: https://github.com/spape/yard-rest-plugin
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.21
+signing_key: 
+specification_version: 3
+summary: A customized plugin for Yardoc that produces API documentation for Restful
+  web services
+test_files: []