httpdoc 0.2.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Alexander Staubo
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,137 @@
+Httpdoc is a very simple documentation generator for generating public API documentation for an HTTP-based web service, parsed from comments embedded in Ruby source code. It's API philosophy-agnostic and supports REST and such if you like. For example, an HTTP API can be described like so:
+
+    ## List stuff.
+    #
+    # @return A list of stuff in XML.
+    # @status 200
+    # @status 403 If you do not have permission to list the stuff.
+    # @example
+    #   @request
+    #   GET #{base_url}/create/31
+    #   
+    #   @response
+    #   HTTP/1.1 200 OK
+    #   Content-Type: application/xml; charset=utf-8
+    #
+    #   <stuff>...</stuff>
+    # @end
+    #
+    def list
+      ...
+    end
+
+Limitations
+-----------
+
+Httpdoc is currently limited to Rails applications. I plan to generalize the internals to support Sinatra and other frameworks, which should be quite trivial.
+
+Since Httpdoc does not read Rails routes, it currently requires per-action URL paths to be explicitly written out in the documentation strings. I will be working on route inference.
+
+For historic reasons, only Textile and HTML is supported in documentation fragments. I plan to phase out Textile and make Markdown the default format.
+
+Format
+------
+
+The documentation format is vaguely inspired by JavaDoc conventions.
+
+All documentation comments are indicated by double hashes, like so:
+
+    ## This line introduces a documentation comment, and
+    # this line continues it.
+
+This first part of the documentation comment is the main description of the class or action.
+
+Attributes consist of a key and a value:
+
+    # @foo Bar
+
+Here, `foo` is an attribute, and `Bar` is its value. Attributes can have multi-line values; a value ends when the next attribute starts or the entire documentation comment terminates.
+
+Some attributes take two arguments, such as in the case of `param`:
+
+    # @param key Some key.
+    
+Here, `key` is a parameter name, `Some key` is its description. See below.
+
+A controller class is preceded by a block which introduces the controller:
+
+    ## This API does stuff.
+    class StuffController < ApplicationController
+    
+A controller class supports two attributes, `title` and `url`:
+
+* `@title [title]`: specify a heading for the API itself.
+    
+* `@url [url]`: a base URL or relative path for the API. This is combined with the `--base-url` option passed to Httpdoc on the command line. Currently Httpdoc does not infer this stuff from Rails routes, so it can be overridden here if the controller name does not match the actual path used.
+
+For example:
+
+    ## This API does stuff.
+    #
+    # @title Stuff
+    # @url http://stuff.ly/api/
+    #
+    class StuffController < ApplicationController
+
+Methods are described thusly:
+
+    ## Create stuff that can be shared with other users.
+    #
+    def create
+      ...
+    end
+    
+Methods support the following attributes:
+
+* `@param [name] [description]`: which describes a parameter name.
+
+* `@status [code] [description]`: describes a possible HTTP status code and its meaning.
+
+* `@return [description]`: says what the action produces in terms of output.
+
+* `@short [description]`: specifies a short description, usable as a title.
+
+* `@url [url]`: specifies the URL of the HTTP call, either an absolute URL or a relative path. This is combined with the `@url` attribute on the class itself, and the `--base-url` option passed to Httpdoc on the command line. Currently Httpdoc does not infer this stuff from Rails routes, so it can be overridden here if the controller name does not match the actual path used. If not specified, the name of the method itself is assumed.
+
+* `@example`: introduces an example block. It's terminated with an `@end` attribute. Within the example block, `@request` introduces the request, and `@response` the response.
+
+Here's a complete example of a method doc:
+
+    ## Create stuff that can be shared with other users.
+    #
+    # @url create/:amount
+    # @short Create stuff
+    # @param amount The amount of stuff to create, an integer between 3 and 42.
+    # @return The URL to the stuff.
+    # @status 201
+    # @status 403 If you do not have permission to create the stuff.
+    # @example
+    #   @request
+    #   POST #{base_url}/create/31
+    #   
+    #   @response
+    #   HTTP/1.1 201 Created
+    #   Content-Type: text/plain; charset=utf-8
+    #
+    #   http://#{base_url}/stuff/9953
+    # @end
+    #
+    def create
+      ...
+    end
+
+Usage
+-----
+
+To generate documentation for a bunch of controllers:
+
+    httpdoc --base-url=http://mysite.com/api/v2/ --template=mytemplate --output-dir=doc/ app/controllers/api/v2/*.rb
+
+Look in the `examples` directory for an example controller and its pre-generated documentation example. To generate the example controller's documentation, using the example template:
+
+    httpdoc -t examples/single_file_template.erb -o examples/ examples/*.rb
+    
+Requirements
+------------
+
+* RedCloth

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/bin/httpdoc

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'httpdoc'
+
+template_name = 'single_file'
+base_url = 'http://example.org/'
+output_directory = '.'
+
+ARGV.options do |opts|
+  opts.banner = "Usage: #{File.basename($0)} [OPTIONS ...] [INPUT ...]"
+  opts.separator ""
+  opts.on("-t", "--template=TEMPLATE", String, "Specify template (default: #{template_name})") do |value| 
+    template_name = value
+  end
+  opts.on("-o", "--output-dir=DIRECTORY", String, "Output directory (defaults to current directory)") do |value| 
+    output_directory = value
+  end
+  opts.on("--base-url=URL", String, "Base URL of HTTP interface (eg., http://myapp.org/)") do |value| 
+    base_url = value
+  end
+  opts.on("-h", "--help", "Show this help message.") do
+    puts opts
+    exit
+  end
+  opts.parse!
+  if ARGV.empty?
+    puts "Nothing to do. Run with -h for help."
+    exit
+  end
+end
+
+generator = Httpdoc::Generator.new
+generator.output_directory = output_directory
+generator.template_name = template_name
+generator.input_paths = ARGV
+generator.base_url = base_url
+generator.generate!

data/lib/httpdoc/generator.rb

@@ -0,0 +1,36 @@
+module Httpdoc
+  
+  class Generator
+    
+    attr_accessor :base_url
+    attr_accessor :output_directory
+    attr_accessor :input_paths
+    attr_accessor :template_name
+    
+    def generate!
+      file_names = @input_paths.map { |path|
+        path = path.gsub(/\/$/, '')
+        if File.file?(path)
+          path
+        else
+          Dir.glob("#{path}/**/*_controller.rb")
+        end
+      }.flatten
+      file_names.each do |file_name|
+        parser = RubyCommentParser.new(file_name)
+        parser.parse
+        if parser.controller
+          renderer = Rendering::SingleFileRenderer.new(:base_url => @base_url)
+          renderer.template_name = @template_name
+          output_filename = File.join(@output_directory, File.basename(file_name).gsub(/\.rb/, ''))
+          output_filename << ".html"
+          File.open(output_filename, "w") do |file|
+            file << renderer.render_controller(parser.controller)
+          end
+        end
+      end      
+    end
+    
+  end
+
+end

data/lib/httpdoc/model.rb

@@ -0,0 +1,47 @@
+module Httpdoc
+
+  class Parameter
+    attr_accessor :name
+    attr_accessor :description
+  end
+  
+  class Example
+    attr_accessor :request
+    attr_accessor :response
+  end
+
+  class Status
+    attr_accessor :code
+    attr_accessor :description
+  end
+  
+  class Action
+    def initialize
+      @parameters = []
+      @examples = []
+      @statuses = []
+    end
+    
+    attr_accessor :url
+    attr_accessor :short_description
+    attr_accessor :description
+    attr_accessor :parameters
+    attr_accessor :examples
+    attr_accessor :statuses
+    attr_accessor :return
+  end
+  
+  class Controller
+    def initialize
+      @actions = []
+      @constants = {}
+    end
+
+    attr_accessor :title
+    attr_accessor :description
+    attr_accessor :actions
+    attr_accessor :constants
+    attr_accessor :url
+  end
+  
+end

data/lib/httpdoc/parser.rb

@@ -0,0 +1,166 @@
+module Httpdoc
+
+  module ControllerDocParser
+    
+    def self.parse(doc)
+      controller = Controller.new
+      if doc =~ /\A(.*?)^\s*@/m
+        controller.description = $1.strip
+      end
+      doc.scan(/@title\s+(.*?)(^[@]|\z)/m).each do |s|
+        controller.title = $1.strip
+        break
+      end
+      doc.scan(/@url\s+(.*?)(?=^@|\z)/m) do
+        controller.url = $1.strip
+        break
+      end
+      controller
+    end
+    
+  end
+  
+  module ActionDocParser
+    
+    def self.parse(name, doc, actions = [])
+      action = Action.new
+      if doc =~ /\A(.*?)^\s*@/m
+        action.description = $1.strip
+      end
+      doc.scan(/@param\s+(.*?)(?:\s+(.*?))?(?=^\s*@|\z)/m) do
+        param = Parameter.new
+        param.name = $1
+        param.description = $2
+        action.parameters << param
+      end
+      doc.scan(/@status\s+(.*?)(?:\s+(.*?))?(?=^\s*@|\z)/m) do
+        status = Status.new
+        status.code = $1.strip
+        status.description = $2.strip
+        action.statuses << status
+      end
+      doc.scan(/@return\s+(.*?)(?=^@|\z)/m) do
+        action.return = $1.strip
+        break
+      end
+      doc.scan(/@short\s+(.*?)(?=^@|\z)/m) do
+        action.short_description = $1.strip
+        break
+      end
+      doc.scan(/@url\s+(.*?)(?=^@|\z)/m) do
+        action.url = $1.strip
+        break
+      end
+      action.url ||= name
+      doc.scan(/@example\s*\n(.*?)(^\s*@end|\z)/m) do
+        example = Example.new
+        s = $1
+        s.scan(/(^[\t ]*)@request\s+(.*?)(?=^\s*@|\z)/m) do
+          padding, req = $1, $2
+          example.request = req.split("\n").map { |line|
+            line = line[padding.length..-1] || '' if line[0, padding.length] == padding
+            line
+          }.join("\n")
+          break
+        end
+        s.scan(/(^[\t ]*)@response\s+(.*?)(?=^\s*@|\z)/m) do
+          padding, res = $1, $2
+          example.response = res.split("\n").map { |line|
+            line = (line[padding.length..-1] || '') if line[0, padding.length] == padding
+            line
+          }.join("\n")
+          break
+        end
+        action.examples << example
+        break
+      end
+      actions << action
+      actions
+    end
+    
+  end
+  
+  class RubyCommentParser
+    
+    def initialize(file_name)
+      @file_name = file_name
+    end
+    
+    def parse
+      reset
+      File.open(@file_name) do |file|
+        file.readlines.each do |line|
+          case @state
+            when :top
+              case line
+                when /\A\s*##(.*)/
+                  @buffer << $1
+                  @buffer << "\n"
+                  @state = :class_doc
+              end
+            when :class_doc
+              case line
+                when /\A\s*#+\s?(.*)/
+                  @buffer << $1
+                  @buffer << "\n"
+                when /(^|\s*)class \w/
+                  unless @buffer.empty?                    
+                    @controller = ControllerDocParser.parse(@buffer)
+                    @buffer = ''
+                  end                  
+                  @state = :class_def
+              end              
+            when :class_def
+              case line
+                when /^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)/
+                  if @controller
+                    @controller.constants[$1] = $2
+                  end
+                when /\A\s*##(.*)/
+                  @buffer << $1
+                  @state = :method_def
+              end
+            when :method_def
+              case line
+                when /\A\s*#+\s?(.*)/
+                  @buffer << $1
+                  @buffer << "\n"
+                when /\A\s*def ([^\s#\(]+)/
+                  name = $1
+                  unless @buffer.empty?
+                    if @controller
+                      ActionDocParser.parse(name, @buffer, @controller.actions)
+                    end
+                    @buffer = ''
+                  end
+                  @state = :class_def
+                else
+                  unless @buffer.empty?
+                    if @controller
+                      ActionDocParser.parse(nil, @buffer, @controller.actions)
+                    end
+                    @buffer = ''
+                  end
+                  @state = :class_def
+              end
+          end
+        end
+      end
+      if @controller
+        @controller.url ||= $1 if @file_name =~ /(\w+)_controller\./
+      end
+    end
+    
+    attr_reader :controller
+    
+    private
+    
+      def reset
+        @controller = nil
+        @buffer = ''
+        @state = :top
+      end
+    
+  end
+  
+end

data/lib/httpdoc/rendering.rb

@@ -0,0 +1,156 @@
+require "uri"
+require "erb"
+require "redcloth"
+
+module Httpdoc
+  module Rendering
+
+    class UndefinedVariableError < Exception
+      def initialize(name)
+        super("Undefined variable #{name}")
+        @name = name
+      end
+      attr_reader :name
+    end
+  
+    class UndefinedConstantError < Exception
+      def initialize(name)
+        super("Undefined constant #{name}")
+        @name = name
+      end
+      attr_reader :name
+    end
+
+    class ControllerContext
+      
+      def initialize(renderer, controller)
+        @renderer = renderer
+        @controller = controller
+      end
+      
+      def h(s)
+        s ||= ''
+        return s.gsub(/#\{(.*)\}/) {
+          name = $1
+          case name
+            when /^[A-Z0-9_]+$/
+              value = @controller.constants[name]
+              raise UndefinedConstantError.new(name) unless value
+              value = eval(value)
+            when "base_url"
+              value = base_url.gsub(/\/$/, '')
+            else
+              raise UndefinedVariableError, name
+          end
+          value
+        }
+      end
+      
+      def doc_fragment_to_html(s)
+        s = s.gsub("\n", ' ')
+        RedCloth.new(s).to_html
+      end
+            
+      def expand_url_with_subtitutions(url)
+        url = [base_url, url].join("/") unless url =~ /^\//
+        return URI.join(@renderer.base_url, url).to_s.gsub(/:([\w_]+)/, '<strong>&lt;\1&gt;</strong>')
+      end
+      
+      def base_url
+        controller_url = @controller.url
+        controller_url ||= "/"
+        return URI.join(@renderer.base_url, controller_url).to_s
+      end
+      
+      def escape_html(h)
+        return nil unless h
+        h = h.dup
+        h.gsub!("&", "&amp;")
+        h.gsub!("<", "&lt;")
+        h.gsub!(">", "&gt;")
+        h.gsub!("\n", "<br/>")
+        h
+      end
+      
+      def format_request(req)
+        envelope, body = req.split("\n\n")
+        lines = envelope.split("\n")
+        first_line, header_lines = lines[0], (lines[1..-1] || [])
+        result = "<div class='request'>"
+        result << "<strong class='request_first_line'>#{h(first_line)}</strong><br/>"
+        result << header_lines.map { |h|
+          name, value = h.split(":\s*")
+          "<span class='request_header_line'><strong class='request_header_name'>#{escape_html(name)}" <<
+            "</strong>: <span class='request_header_value'>#{escape_html(value)}</span></span>"
+        }.join("<br/>")
+        if body and body != ''
+          result << "<br/>"
+          result << "<div class='request_body'>#{escape_html(body.strip)}</div>"
+        end
+        result << "</div>"
+        result
+      end
+
+      def format_response(res)
+        envelope, body = res.split("\n\n")
+        lines = envelope.split("\n")
+        first_line, header_lines = lines[0], (lines[1..-1] || [])
+        result = "<div class='response'>"
+        result << "<strong class='response_first_line'>#{h(first_line)}</strong><br/>"
+        result << header_lines.map { |h|
+          name, value = h.scan(/(.+):\s*(.+)/)[0]
+          "<span class='response_header_line'><strong class='response_header_name'>#{escape_html(name)}" <<
+            "</strong>: <span class='response_header_value'>#{escape_html(value)}</span></span>"
+        }.join("<br/>")
+        if body and body != ''
+          result << "<br/><br/>"
+          result << "<div class='response_body'>#{escape_html(body)}</div>"
+        end
+        result << "</div>"
+        result
+      end
+      
+      def get_binding
+        return binding
+      end
+      
+      attr_reader :controller
+      
+    end
+
+    class SingleFileRenderer
+      
+      def initialize(options = {})
+        @base_url = options[:base_url]
+        @base_url ||= 'http://example.com/'
+      end
+      
+      def render_controller(controller)
+        %w(erb).each do |extension|
+          template_file_name = "#{@template_name}"
+          template_file_name = "#{template_file_name}.#{extension}" unless template_file_name =~ /#{Regexp.escape(extension)}$/
+          unless File.exist?(template_file_name)
+            possible_template_file_name = File.join(File.dirname(__FILE__), "templates/#{template_file_name}")
+            if File.exist?(possible_template_file_name)
+              template_file_name = possible_template_file_name
+            end
+          end
+          template_content = File.read(template_file_name)
+          context = ControllerContext.new(self, controller)
+          erb = ERB.new(template_content, nil, "-")
+          return erb.result(context.get_binding)
+        end
+      end
+      
+      def find_template(name)
+        %(erb).each do |extension|
+        end
+      end
+      
+      attr_reader :base_url
+      attr_accessor :template_name
+      
+    end
+    
+  end
+end

data/lib/httpdoc.rb

@@ -0,0 +1,4 @@
+require "httpdoc/generator"
+require "httpdoc/model"
+require "httpdoc/parser"
+require "httpdoc/rendering"

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification 
+name: httpdoc
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
+platform: ruby
+authors: 
+- Alexander Staubo
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-23 00:00:00 +01:00
+default_executable: httpdoc
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: RedCloth
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: Simple documentation generator for publishing APIs from Rails applications.
+email: alex@bengler.no
+executables: 
+- httpdoc
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- LICENSE
+- README.markdown
+- VERSION
+- lib/httpdoc.rb
+- lib/httpdoc/generator.rb
+- lib/httpdoc/model.rb
+- lib/httpdoc/parser.rb
+- lib/httpdoc/rendering.rb
+- bin/httpdoc
+has_rdoc: false
+homepage: http://github.com/origo/httpdoc
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Simple documentation generator for publishing APIs from Rails applications.
+test_files: []
+