api_tommy 0.1.0

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.2.0

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.3
+  - 2.2.0
+script: bundle exec rake test

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,70 @@
+PATH
+  remote: .
+  specs:
+    api_tommy (0.1.0)
+      activesupport (~> 4.2)
+      grit (~> 2.5)
+      rdoc (~> 4.2)
+      tomparse (~> 0.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.2.0)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    ansi (1.5.0)
+    builder (3.2.2)
+    coderay (1.1.0)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    grit (2.5.0)
+      diff-lcs (~> 1.1)
+      mime-types (~> 1.15)
+      posix-spawn (~> 0.3.6)
+    i18n (0.7.0)
+    json (1.8.2)
+    metaclass (0.0.1)
+    method_source (0.8.2)
+    mime-types (1.25.1)
+    minitest (5.5.0)
+    minitest-reporters (1.0.8)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
+    mocha (0.14.0)
+      metaclass (~> 0.0.1)
+    multi_json (1.10.1)
+    posix-spawn (0.3.9)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rake (10.4.2)
+    rdoc (4.2.0)
+    ruby-progressbar (1.7.1)
+    simplecov (0.9.1)
+      docile (~> 1.1.0)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    slop (3.6.0)
+    thread_safe (0.3.4)
+    tomparse (0.4.2)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  api_tommy!
+  minitest-reporters (~> 1.0)
+  mocha (~> 0.14)
+  pry (~> 0.10)
+  rake (~> 10.4)
+  simplecov (~> 0.8)

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 David Fernandez
+
+MIT License
+
+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.md

@@ -0,0 +1,193 @@
+# ApiTommy
+[![Build Status](https://travis-ci.org/gatemedia/api-tommy.svg?branch=master)](https://travis-ci.org/gatemedia/api-tommy)
+
+ApiTommy is an opinionated little tool used to generate a wiki page documenting your APIs based on Rails/Rails-api.
+
+Basically, you document your classes using a standard. There is no modification in your code.
+You then run this tool and it will automatically generate and update your github wiki.
+
+This tool depends on rdoc 4.2.x
+
+# Compatibility
+* rails 4.2.x
+* rdoc 4.2.x
+
+This gem is built against:
+* ruby 1.9.3
+* ruby 2.0.0
+* ruby 2.1.3
+* ruby 2.2.0
+
+Other versions may or may not work.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'api_tommy'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install api_tommy
+
+## Usage
+
+Here is the requirements in order to have an happy tommy (pun intended):
+
+* The best place to document your API is your controllers.
+* Each class/method is documented using [TomDoc](http://tomdoc.org/).
+* For the class comments, here is the usage of each [TomDoc](http://tomdoc.org/) section:
+  * Description: Will describe your API and the returned objects
+  * Returns: Not used.
+  * Arguments: Will describe each field of your objects
+  * Examples: Will provide examples of your object
+  * Raises: Not used.
+* For the method comments, here is the usage of each [TomDoc](http://tomdoc.org/) section:
+  * Description: Will describe your method with its constraints. The first sentence will be used
+    as a title for the wiki.
+  * Returns: Will describe the structure returned. Is it an array? A single object?
+  * Arguments: Will describe each parameter accepted by the method.
+  * Examples: Examples of how do you call your API method.
+  * Raises: Will describe what exceptions can occur. Ideally, it should be http codes(eg 400, 404, ...).
+* You are using Ruby 1.9.3.
+* You are using Rails 3.x or 4.
+* Your project is hosted on github and has a wiki.
+
+Let's see an example. Here a really simple API documented controller:
+
+```ruby
+# This is the cars API. It provides ways to search and get cars.
+# Cars are simple json objects with these fields:
+#
+# brand - the brand of the car
+# model - the model of the car
+# horsepower - the horse power of the car
+# year - the year of the car
+#
+# Examples
+#
+# {
+#   "car": {
+#     "brand": "Mini",
+#     "model": "Cooper S",
+#     "horsepower": 400,
+#     "year": 2050
+#   }
+# }
+class CarsController < ApplicationController
+
+  # Get all cars. This method will return all available cars
+  #
+  # Examples
+  #
+  # GET /cars.json
+  #
+  # Returns all cars as an array under the `cars` field.
+  # Raises 500 if an error occurs
+  def index
+    render :json => Car.all
+  end
+
+  # Get a car. This method will return the given car's id.
+  #
+  # id - the car's id as a string.
+  #
+  # Examples
+  #
+  # GET /cars/1237.json
+  #
+  # Return the given car under the `car`field.
+  # Raises 404 if the car can't be found.
+  # Raises 500 if an error occurs
+  def show
+    render :json => Car.find(params[:id])
+  end
+end
+```
+
+On the root of the project, you can then run the following command:
+```
+rdoc --format apitommy app/controllers/cars_controller.rb
+```
+
+This will lead to a page ```API``` in your project wiki, containing this markup:
+```markdown
+# Cars
+
+This is the cars API. It provides ways to search and get cars. Cars are simple json objects with these fields:
+
+### Fields
+
+| Name | Description
+| --- | ---
+| brand | the brand of the car
+| model | the model of the car
+| horsepower | the horse power of the car
+| year | the year of the car
+
+### Examples
+
+{
+  "car": {
+    "brand": "Mini",
+    "model": "Cooper S",
+    "horsepower": 400,
+    "year": 2050
+  }
+}
+
+## Get all cars
+
+Get all cars. This method will return all available cars
+
+Returns all cars as an array under the `cars` field.
+
+### Examples
+
+GET /cars.json
+
+### Errors
+
+500 if an error occurs
+
+## Get a car
+
+Get a car. This method will return the given car's id.
+
+Return the given car under the `car`field.
+
+### Parameters
+
+| Name | Description
+| --- | ---
+| id | the car's id as a string.
+
+### Examples
+
+GET /cars/1237.json
+
+### Errors
+
+404 if the car can't be found.
+
+500 if an error occurs
+```
+
+## Options
+
+When running ```rdoc --format apitommy```, these options are available:
+* ```--filename FILENAME```: the name of the wiki page. ```API``` by default.
+* ```--header HEADER```: if you wish to include a header on the wiki page. Optionnal.
+* ```--footer FOOTER```: if you wish to include a footer on the wiki page. Optionnal.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end

data/api_tommy.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "api_tommy/version"
+
+Gem::Specification.new do |s|
+  s.name          = "api_tommy"
+  s.version       = ApiTommy::VERSION
+  s.authors       = ["David Fernandez"]
+  s.email         = ["david.fernandez@gatemedia.ch"]
+  s.description   = "This generator takes one or several classes with comments formatted in TomDoc and spits out a single Markdown file"
+  s.summary       = "An API documentation generator based on RDoc and TomDoc"
+  s.homepage      = "https://github.com/gatemedia/api-tommy"
+  s.license       = "MIT"
+
+  s.files         = `git ls-files`.split($/)
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency "rdoc", "~> 4.2"
+  s.add_runtime_dependency "tomparse", "~> 0.4"
+  s.add_runtime_dependency "grit", "~> 2.5"
+  s.add_runtime_dependency "activesupport", "~> 4.2"
+
+  s.add_development_dependency "mocha", "~> 0.14"
+  s.add_development_dependency "pry", "~> 0.10"
+  s.add_development_dependency "minitest-reporters", "~> 1.0"
+  s.add_development_dependency "simplecov", "~> 0.8"
+  s.add_development_dependency "rake", "~> 10.4"
+end

data/lib/api_tommy.rb

@@ -0,0 +1,11 @@
+require "rdoc/rdoc"
+require "api_tommy/version"
+require "api_tommy/error"
+require "api_tommy/markdown"
+require "api_tommy/github"
+require "api_tommy/generator"
+
+require "rdoc/generator/api_tommy"
+
+module ApiTommy
+end

data/lib/api_tommy/error.rb

@@ -0,0 +1,3 @@
+module ApiTommy
+  Error = Class.new(StandardError)
+end

data/lib/api_tommy/generator.rb

@@ -0,0 +1,131 @@
+require "tomparse"
+
+module ApiTommy
+  class Generator
+    def self.setup_options(options)
+      options.dry_run = true
+      op = options.option_parser
+
+      op.on("--filename FILENAME", String, "The output filename") do |filename|
+        options.filename = filename.gsub(/\s+/, "-")
+        unless options.filename.end_with?(".md")
+          options.filename = "#{options.filename}.md"
+        end
+      end
+
+      op.on("--header HEADER", String, "The header filename") do |header|
+        options.header = header
+      end
+
+      op.on("--footer FOOTER", String, "The footer filename") do |footer|
+        options.footer = footer
+      end
+    end
+
+    private
+
+    def generate_class_doc(clazz)
+      generate_class_header(clazz)
+      clazz.instance_method_list.each { |method| generate_method_doc(method) }
+    end
+
+    def generate_class_header(clazz)
+      @content << @h.h1(clazz.name.gsub(/Controller/, ""))
+      @tomdoc = TomParse.parse(comment(clazz).split("---").first)
+      @content << @h.p(@tomdoc.description)
+
+      arguments("Fields")
+      examples
+    end
+
+    def generate_method_doc(method)
+      @tomdoc = TomParse.parse(comment(method))
+      @content << @h.h2(@tomdoc.description.split(".").first)
+      @content << @h.p(@tomdoc.description)
+
+      returns
+      arguments
+      examples
+      raises
+    end
+
+    def arguments(title = "Parameters")
+      return if @tomdoc.arguments.empty?
+      @content << @h.h3(title)
+      @content << @h.th("Name", "Description")
+      @tomdoc.arguments.each do |a|
+        @content << @h.tr(a.name.to_s, a.description)
+      end
+    end
+
+    def examples
+      return if @tomdoc.examples.empty?
+      @content << @h.h3("Examples")
+      @tomdoc.examples.each do |e|
+        @content << @h.code(e.to_s)
+      end
+    end
+
+    def returns
+      return if @tomdoc.returns.empty?
+      @tomdoc.returns.each do |r|
+        @content << @h.p(r.to_s)
+      end
+    end
+
+    def raises
+      return if @tomdoc.raises.empty?
+      @content << @h.h3("Errors")
+      @tomdoc.raises.each do |r|
+        @content << @h.p(r.to_s.gsub(/Raises\s/, ""))
+      end
+    end
+
+    def comment(object)
+      result = object.comment
+      return result if result.is_a?(String)
+      result.text
+    end
+
+    def log(message, level = :info)
+      puts "[#{level}] #{message}"
+    end
+
+    def finalize_content
+      in_doc_folder do
+        if @options.header
+          @content = "#{File.read(@options.header)}\n#{@content}"
+        end
+        @content << File.read(@options.footer) if @options.footer
+      end
+    end
+
+    def update_wiki
+      in_doc_folder do
+        if $DEBUG_RDOC
+          filepath = File.join(%W(doc #{@options.filename || "api_tommy.md"}))
+          log("Writing to local file: #{filepath}", :warning)
+          File.open(filepath, "w") { |f| f.write(@content) }
+        else
+          log("Updating Github wiki...")
+          Github.new.update_wiki(@options.filename || "API.md", @content)
+        end
+        log("Done.")
+      end
+    end
+
+    def in_doc_folder
+      FileUtils.cd(Dir.pwd.end_with?("/doc") ? ".." : Dir.pwd) do
+        yield
+      end
+    end
+  end
+end
+
+# Monkey patch to add accessors
+# this is bad. TODO find a better way
+module RDoc
+  class Options
+    attr_accessor :filename, :header, :footer
+  end
+end