api_blueprint 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3c06b5d206b8bf0f3ca2d9540ce47da6200ff8c5
+  data.tar.gz: 1979c9532714e356234d04858b37b437629d674a
+SHA512:
+  metadata.gz: ff4835d306e95aa438ef3cfeaed9e777c3600e0beaaa6f0eb3b5569a544060b19c0c4ed4879eac9bc17bf1e47385c87f9618237c6a837cfb2833e5a5b8e8dd32
+  data.tar.gz: 7811e24b5dfdd4912635ca738657e0c888b12520ae4b5a7cd6f616dd2ca075cfed70dd730c36c275d252075cdd157e454c3ae557be7d2ec250a1872fe1c7342b

data/README.md

@@ -0,0 +1,100 @@
+# api-blueprint
+
+Semi-automatic solution for creating Rails app's API documentation. Here's how it works:
+
+1. You start with method list generated from RSpec request specs. For each method, you get a list of parameters and examples.
+2. Then, you can extend it in whatever way you need using Markdown syntax. You can organize documentation files into partials.
+3. Upon any API change, like serializer change that changes responses, you can update automatically generated parts of docs.
+4. Once done, you can compile your documentation into single, nicely styled HTML file. You can also auto-deploy it via SSH.
+
+## Installation
+
+Add to `Gemfile`:
+
+```ruby
+gem 'api_blueprint', group: [:development, :test]
+```
+
+Then run:
+
+    bundle install
+
+Add the following inside `RSpec.configure` block in `spec/spec_helper.rb`:
+
+```ruby
+config.include ApiBlueprint::Collect::SpecHook
+```
+
+## Usage
+
+**api-blueprint** consists of two modules:
+
+1. **Collect** module: allows to run RSpec request suite in order to auto-generate API method information.
+2. **Compile** module: allows to turn whole Markdown documentation into single, ready-to-publish HTML file.
+
+### Collect
+
+In order to auto-generate API method information you should invoke:
+
+    rake blueprint:collect
+
+> By default, all specs inside `spec/requests/api` are run. You can configure that by creating a [Blueprintfile](#configuration) configuration.
+
+This will generate the `doc/api.md` file with a Markdown documentation ready to compile. If this file already exists, **api-blueprint** will not override it. It will write to `tmp/merge.md` instead so you can merge both existing and generated documentation manually in whatever way you want.
+
+Of course, it's just a starting point and you should at least fill in some resource, action and parameter descriptions. But that's a story for the **Compile** module.
+
+#### Regenerate examples
+
+You get the RSpec-based example listing for every auto-generated API method documentation. There's a chance that
+
+### Compile
+
+In order to turn your documentation into ready-to-publish HTML file you should invoke:
+
+    rake blueprint:compile
+
+This will create the final `doc/api.html`. You can deploy this file to configured SSH target with:
+
+    rake blueprint:deploy
+
+If you want to preview this file constantly when editing Markdown docs, you can do so with:
+
+    rake blueprint:watch
+
+> You should add `doc/**/*.html` to your `.gitignore` as there's no need to clutter your project history with compiled HTML that you can easily recreate on demand.
+
+#### Require another file
+
+You can split your documentation into separate files and directories in order to organize it better and reuse same fragments in multiple places. You can do that with the following Markdown:
+
+```md
+<require:fragments/deprecation_warning.md>
+```
+
+## Configuration
+
+Configuration for **api-blueprint** lives in `Blueprintfile` inside application directory. It's basically a listing of documentations governed by **api-blueprint**, each with a set of options. It looks like this:
+
+```yaml
+api:
+  spec: "spec/requests/api/v2"
+  blueprint: "doc/api.md"
+  html: "doc/api.html"
+  deploy: "user@server.com:/home/app/public/api.html"
+  naming:
+    sessions:
+      create: "Sign In"
+```
+
+Here's what specific per-documentation options stand for:
+
+Option | Description
+-------|------------
+`spec` | RSpec spec suite directory
+`blueprint` | Main documentation file (Markdown)
+`html` | Target HTML file created after compilation
+`deploy` | SSH address used for documentation deployment
+`naming` | Dictionary of custom API method names
+
+First group is always a default one. You can switch any rake task to work on other group by specifying its name with `rake blueprint:collect group=other`.

data/lib/api_blueprint/collect/controller_hook.rb

@@ -0,0 +1,92 @@
+module ApiBlueprint::Collect::ControllerHook
+  def self.included(base)
+    return unless ENV['API_BLUEPRINT_DUMP'] == '1'
+
+    base.around_filter :dump_blueprint_around
+  end
+
+  class Parser
+    attr_reader :input
+
+    def initialize(input)
+      @input = input
+    end
+
+    def method
+      input.method.to_s.upcase
+    end
+
+    def params
+      JSON.parse(input.params.reject do |k,_|
+        ['action', 'controller'].include?(k)
+      end.to_json)
+    end
+
+    def headers
+      Hash[input.headers.env.select do |k, v|
+        (k.start_with?("HTTP_X_") || k == 'ACCEPT') && v
+      end.map do |k, v|
+        [human_header_key(k), v]
+      end]
+    end
+
+    def body
+      if input.content_type == 'application/json'
+        if input.body != 'null'
+          JSON.parse(input.body)
+        else
+          ""
+        end
+      else
+        input.body
+      end
+    end
+
+    private
+
+    def human_header_key(key)
+      key.sub("HTTP_", '').split("_").map do |x|
+        x.downcase
+      end.join("_")
+    end
+  end
+
+  def dump_blueprint_around
+    yield
+  ensure
+    dump_blueprint
+  end
+
+  def dump_blueprint
+    file       = ApiBlueprint::Collect::Storage.request_dump
+    in_parser  = Parser.new(request)
+    out_parser = Parser.new(response)
+
+    data = {
+      'request' => {
+        'path'         => request.path,
+        'method'       => in_parser.method,
+        'params'       => in_parser.params,
+        'headers'      => in_parser.headers,
+        'content_type' => request.content_type,
+        'accept'       => request.accept
+      },
+      'response' => {
+        'status'       => response.status,
+        'content_type' => response.content_type,
+        'body'         => out_parser.body
+      },
+      'route' => {
+        'controller'   => controller_name,
+        'action'       => action_name
+      }
+    }
+
+    spec = ApiBlueprint::Collect::Storage.spec_dump
+    if File.exists?(spec)
+      data['spec'] = YAML::load_file(spec)
+    end
+
+    File.write(file, data.to_yaml)
+  end
+end

data/lib/api_blueprint/collect/merge.rb

@@ -0,0 +1,334 @@
+class ApiBlueprint::Collect::Merge
+  attr_reader :target, :renderer, :preprocessor
+
+  def initialize(options)
+    @target       = options[:target]
+    @logger       = options[:logger]
+
+    @renderer     = ApiBlueprint::Collect::Renderer.new
+    @preprocessor = ApiBlueprint::Collect::Preprocessor.new(
+      :naming => options[:naming])
+  end
+
+  def merge
+    log "Merging into '#{@target}'..."
+
+    File.write(target, body_content)
+  end
+
+  def update_examples
+    log "Updating examples in '#{@target}'..."
+    log ''
+
+    library.each do |resource, actions|
+      actions.each do |action, info|
+        log "#{resource}: #{action}\n\n"
+
+        info[:requests].each do |request|
+          insert = find_insertion_point(resource, action, request[:title])
+
+          if insert && insert[1] == nil
+            insert_example_block(insert, request)
+          elsif insert
+            replace_example_block(insert, request)
+          else
+            log "no insertion point: #{request_title request}", :error
+          end
+        end
+
+        log ''
+      end
+    end
+  end
+
+  def clear_examples
+    log "Clearing examples in '#{@target}'...\n\n"
+
+    library.each do |resource, actions|
+      actions.each do |action, info|
+        clear = find_clear_point(resource, action)
+
+        log "#{resource}: #{action}\n\n"
+
+        if clear
+          clear_example_block(clear)
+        else
+          log "no clear point", :error
+        end
+
+        log ''
+      end
+    end
+  end
+
+  private
+
+  # library loading
+
+  def library
+    @library ||= begin
+      resources = {}
+
+      requests.each do |request|
+        resource = (resources[preprocessor.resource_name(request)] ||= {})
+        action = (resource[preprocessor.action_name(request)] ||= {
+          :requests => []
+        })
+
+        action[:requests] << request
+      end
+
+      resources.each do |resource, actions|
+        actions.each do |action, info|
+          preprocessor.preprocess(info)
+        end
+      end
+
+      resources = resources.sort
+
+      resources
+    end
+  end
+
+  def requests
+    ApiBlueprint::Collect::Storage.request_dumps.collect do |file|
+      YAML::load_file(file)
+    end.uniq
+  end
+
+  # content assembly
+
+  def body_content
+    library.collect do |resource, actions|
+      text = renderer.resource_header(resource)
+
+      text += actions.collect do |action, info|
+        text = renderer.action_header(action)
+
+        text += renderer.description_header
+        text += renderer.signature(info[:path], info[:method])
+        text += renderer.parameter_table(info[:params])
+        text += examples(info)
+      end.join
+    end.join
+  end
+
+  def examples(info)
+    text = renderer.examples_header
+
+    text += info[:requests].collect do |request|
+      example(request)
+    end.join
+  end
+
+  def example(request)
+    text = renderer.example_header(request[:title])
+
+    if request[:request_headers].present?
+      text += renderer.example_subheader(:request_headers) +
+      renderer.code_block(request[:request_headers])
+    end
+
+    if request[:params]
+      text += renderer.example_subheader(:request_params) +
+      renderer.code_block(request[:params])
+    end
+
+    text += renderer.example_subheader(:response_headers) +
+      renderer.code_block(request[:response_headers]) +
+      renderer.example_subheader(:response_body) +
+      renderer.code_block(request[:body])
+  end
+
+  # example updating
+
+  def find_insertion_point(resource, action, example)
+    @partial_map = build_partial_map(@target)
+
+    resource = find_chapter(1, "Resource: #{resource}")
+    return nil unless resource
+
+    action   = find_chapter(2, "Action: #{action}", resource)
+    return nil unless action
+
+    examples = find_chapter(3, "Examples:", action)
+    return nil unless examples
+
+    example  = find_chapter(4, "Example: #{example}", examples)
+
+    if example
+      example
+    else
+      [examples[1], nil]
+    end
+  end
+
+  def find_clear_point(resource, action)
+    @partial_map = build_partial_map(@target)
+
+    resource = find_chapter(1, "Resource: #{resource}")
+    return nil unless resource
+
+    action   = find_chapter(2, "Action: #{action}", resource)
+    return nil unless action
+
+    examples = find_chapter(3, "Examples:", action)
+    return nil unless examples
+
+    [examples[0] + 2, examples[1]]
+  end
+
+  def find_chapter(level, title, constraints = nil)
+    from = constraints ? constraints[0] : 0
+    to   = constraints ? constraints[1] : @partial_map.length - 1
+
+    point = []
+
+    @partial_map[from..to].each_with_index do |line, index|
+      map_index = from + index
+
+      if line[0].strip == (('#' * level) + ' ' + title)
+        point[0] = map_index
+      elsif point[0].present? && line[0].match(/^\#{1,#{level}}\s/)
+        point[1] = map_index - 1
+
+        break
+      end
+    end
+
+    if point[0]
+      point[1] ||= to
+
+      point
+    else
+      nil
+    end
+  end
+
+  def insert_example_block(insert, request)
+    insert_map = @partial_map[insert[0]]
+
+    file = insert_map[1]
+    at   = insert_map[2]
+
+    log "#{file} @ #{at}: #{request_title request}", :add
+
+    e = example(request).split("\n").map { |l| l + "\n" }
+
+    lines = File.readlines(file)
+    if lines[at].present?
+      lines.insert(at + 1, "\n")
+      at += 1
+    end
+    if lines[at + 1].present?
+      lines.insert(at + 1, "\n")
+    end
+    lines = lines[0..at] + e + lines[at + 1..-1]
+
+    File.write(file, lines.join(''))
+  end
+
+  def replace_example_block(insert, request)
+    from_map = @partial_map[insert[0]]
+    to_map   = @partial_map[insert[1]]
+
+    unless from_map[1] == to_map[1]
+      return log("[!] multi-file range: #{request_title request}")
+    end
+
+    file = from_map[1]
+    from = from_map[2] - 1
+    to   = to_map[2] + 1
+
+    log "#{file} @ #{from}-#{to}: #{request_title request}", :modify
+
+    e = example(request).split("\n").map { |l| l + "\n" }
+
+    lines = File.readlines(file)
+    if lines[to].present?
+      lines.insert(to, "\n")
+    end
+    lines = lines[0..from] + e + lines[to..-1]
+
+    File.write(file, lines.join(''))
+  end
+
+  def clear_example_block(clear)
+    from_map = @partial_map[clear[0]]
+    to_map   = @partial_map[clear[1]]
+
+    unless from_map and to_map
+      return log('wrong mapping', :error)
+    end
+
+    unless from_map[1] == to_map[1]
+      return log("multi-file range", :error)
+    end
+
+    file = from_map[1]
+    from = from_map[2] - 1
+    to   = to_map[2] + 1
+
+    lines = File.readlines(file)
+    if lines[from].blank? && lines[to].blank?
+      to += 1
+    end
+
+    log "#{file} @ #{from}-#{to}", :remove
+
+    final_lines = lines[0..from]
+    final_lines += lines[to..-1] if lines[to..-1]
+
+    File.write(file, final_lines.join(''))
+  end
+
+  def build_partial_map(file)
+    lines = File.readlines(file)
+    map = []
+
+    lines.each_with_index do |line, index|
+      if line.start_with?("<require:")
+        filename = line.split('<require:')[1].split('>')[0] + '.md'
+        path = file.split('/')[0..-2].join('/')
+
+        map += build_partial_map(path + '/' + filename)
+      else
+        map << [line, file, index]
+      end
+    end
+
+    map
+  end
+
+  def request_title(request)
+    limit = 60
+    title = request[:title].strip
+
+    if title.length < limit + 2
+      title
+    else
+      title[0..limit] + '(...)'
+    end
+  end
+
+  # other
+
+  def log(message, kind = nil)
+    if @logger.to_s == 'stdout'
+      message = case kind.to_s
+      when 'error'
+        (' ! ' + message).colorize(:red)
+      when 'add'
+        (' + ' + message).colorize(:green)
+      when 'modify'
+        (' * ' + message).colorize(:magenta)
+      when 'remove'
+        (' - ' + message).colorize(:cyan)
+      else
+        message
+      end
+
+      puts message
+    end
+  end
+end

data/lib/api_blueprint/collect/preprocessor.rb

@@ -0,0 +1,175 @@
+class ApiBlueprint::Collect::Preprocessor
+  attr_reader :naming
+
+  def initialize(options = {})
+    @naming = options[:naming]
+  end
+
+  def resource_name(request)
+    request['route']['controller'].singularize.split('_').map do |word|
+      word.camelize
+    end.join(' ').pluralize
+  end
+
+  def action_name(request)
+    model = resource_name(request)
+    prefix = %w{a e i o u}.include?(model[0].downcase) ? 'an' : 'a'
+
+    if (n = naming) && (n = n[model.underscore]) && (n = n[request['route']['action']])
+      return n
+    end
+
+    case request['route']['action']
+    when 'index'
+      "List all #{model.pluralize}"
+    when 'show'
+      "Retrieve single #{model.singularize}"
+    when 'update'
+      "Update an existing #{model.singularize}"
+    when 'destroy'
+      "Remove an existing #{model.singularize}"
+    else
+      request['route']['action'].humanize + " #{prefix} #{model.singularize}"
+    end
+
+    # request['route']['action'].humanize
+  end
+
+  def preprocess(info)
+    any_request = info[:requests].first
+
+    info[:path]   = any_request['request']['path'].sub(/\d+$/, '{id}')
+    info[:method] = any_request['request']['method']
+    info[:params] = collect_request_params(info[:requests])
+
+    info[:requests].each do |request|
+      preprocess_request(request)
+    end
+
+    unique_requests = []
+    info[:requests].each do |request|
+      unique_requests.reject! do |existing_request|
+        existing_request[:title] == request[:title]
+      end
+
+      unique_requests.push(request)
+    end
+    info[:requests] = unique_requests
+  end
+
+  private
+
+  def collect_request_params(requests)
+    merged_params = {}
+    requests.sort_by do |request|
+      -request['response']['status']
+    end.each do |request|
+      merged_params.deep_merge!(request['request']['params'])
+    end
+
+    merged_params = Hash[merged_params.select { |k,v| ! v.is_a?(Hash) || v.any? }]
+
+    collect_merged_params(merged_params)
+  end
+
+  def collect_merged_params(merged_params)
+    params = {}
+    merged_params.each do |param, value|
+      if value.is_a?(Hash)
+        if value['original_filename'].present?
+          params[param] = {
+            :type     => 'file',
+            :example  => value['original_filename']
+          }
+        else
+          params[param] = {
+            :type   => 'nested',
+            :params => collect_merged_params(value)
+          }
+        end
+      elsif value.is_a?(Array)
+        items = value.collect { |i| collect_merged_params(i) }
+
+
+        params[param] = {
+          :type   => 'array',
+          :params => items.inject(&:merge)
+        }
+      else
+        if value == true || value == false
+          type = 'boolean'
+          value = value ? 'true' : 'false'
+        elsif value.to_i.to_s == value
+          type = 'integer'
+        elsif value.to_f.to_s == value
+          type = 'decimal'
+          value = value.to_f.round(6).to_s
+        else
+          type = 'string'
+        end
+
+        params[param] = {
+          :type    => type,
+          :example => value
+        }
+      end
+    end
+
+    params
+  end
+
+  def clear_files(params)
+    p = {}
+
+    params.each do |key, value|
+      if value.is_a?(Hash)
+        if value['original_filename'].present?
+          p[key] = "file <#{value['original_filename']}>"
+        else
+          p[key] = clear_files(value)
+        end
+      else
+        p[key] = value
+      end
+    end
+
+    p
+  end
+
+  def preprocess_request(request)
+    if request['request']['params'].present?
+      params = Hash[request['request']['params'].select { |k, v| ! v.is_a?(Hash) || v.any?}]
+      params = clear_files(params)
+      request[:params] = JSON.pretty_generate(params) if params.any?
+    end
+
+    if request['response']['body'].is_a?(Hash)
+      request[:body] = JSON.pretty_generate(request['response']['body'])
+    else
+      request[:body] = request['response']['body']
+    end
+
+    request[:request_headers] = preprocess_headers({
+      # 'Accept' => request['request']['accept'],
+      'Content-Type' => request['request']['content_type']
+    }.merge(request['request']['headers']).select { |_, v| v.present? })
+
+    request[:response_headers] = preprocess_headers({
+      'Status' => request['response']['status'],
+      'Content-Type' => request['response']['content_type']
+    })
+
+    request[:title] = request['spec']['title_parts'][1..-1].join(' ')
+    request[:title] = request[:title][0].upcase + request[:title][1..-1]
+  end
+
+  def preprocess_headers(headers)
+    header_key_length = headers.collect do |key, _|
+      key.length
+    end.max
+
+    headers.collect do |key, value|
+      "#{key.split("_").map(&:camelize).join("-")}:#{' ' * (header_key_length - key.length)} #{value}"
+    end.join("\n")
+  end
+end

data/lib/api_blueprint/collect/renderer.rb

@@ -0,0 +1,70 @@
+class ApiBlueprint::Collect::Renderer
+  def parameter_table(params, level = 0)
+    text = ''
+
+    if level == 0
+      text += "#### Parameters:\n\n"
+      text += "Name | Type | Description\n"
+      text += "-----|------|---------|------------\n"
+    end
+
+    params.each do |name, info|
+      comment = ''
+      comment = "Params for each #{name.singularize}:" if info[:type] == 'array'
+
+      text += "#{'[]' * level} #{name} | *#{info[:type]}*#{info[:example].present? ? " `Example: #{info[:example]}`" : ''} | #{comment}\n"
+
+      if info[:type] == 'nested' || info[:type] == 'array'
+        text += parameter_table(info[:params], level + 1)
+      end
+    end
+    text += "\n" if level == 0
+
+    # text += "#### Parameters:\n\n" if level == 0
+    # text += params.collect do |name, info|
+    #   if info[:type] == 'nested'
+    #     "#{' ' * (level * 2)}- **#{name}**\n" +
+    #       parameter_table(info[:params], level + 1)
+    #   else
+    #     "#{' ' * (level * 2)}- **#{name}** (#{info[:type]}, `#{info[:example]}`)"
+    #   end
+    # end.join("\n")
+    # text += "\n\n" if level == 0
+
+    text
+  end
+
+  def resource_header(content)
+    "# Resource: #{content}\n\n"
+  end
+
+  def action_header(content)
+    "## Action: #{content}\n\n"
+  end
+
+  def description_header
+    "### Description:\n\n"
+  end
+
+  def signature(url, method)
+    "#### Signature:\n\n**#{method}** `#{url}`\n\n"
+  end
+
+  def examples_header
+    "### Examples:\n\n"
+  end
+
+  def example_header(content)
+    "#### Example: #{content}\n\n"
+  end
+
+  def example_subheader(content)
+    content = content.to_s.humanize + ':' if content.is_a?(Symbol)
+
+    "##### #{content}\n\n"
+  end
+
+  def code_block(content)
+    content.split("\n").collect { |line| " " * 4 + line }.join("\n") + "\n\n"
+  end
+end

data/lib/api_blueprint/collect/spec_hook.rb

@@ -0,0 +1,28 @@
+module ApiBlueprint::Collect::SpecHook
+  def self.included(base)
+    return unless ENV['API_BLUEPRINT_DUMP'] == '1'
+
+    base.before(:each) do |example|
+      data = {
+        'title_parts' => example_description_parts(example)
+      }
+
+      File.write(ApiBlueprint::Collect::Storage.spec_dump, data.to_yaml)
+    end
+  end
+
+  private
+
+  def example_description_parts(example)
+    parts = []
+    parts << example.metadata[:description_args].join(' ')
+    at = example.metadata[:example_group]
+
+    while at && at[:description_args]
+      parts << at[:description_args].join(' ')
+      at = at[:parent_example_group]
+    end
+
+    parts.reverse!
+  end
+end

data/lib/api_blueprint/collect/storage.rb

@@ -0,0 +1,14 @@
+module ApiBlueprint::Collect::Storage
+  def self.request_dumps
+    Dir[Rails.root.join('tmp', 'api_blueprint_request_*.yml').to_s]
+  end
+
+  def self.spec_dump
+    Rails.root.join('tmp', 'api_blueprint_spec.yml')
+  end
+
+  def self.request_dump
+    Rails.root.join('tmp',
+      "api_blueprint_request_#{(Time.now.to_f * 1000).to_i}_#{sprintf("%09d", rand(1e9))}.yml")
+  end
+end

data/lib/api_blueprint/compile/compile.rb

@@ -0,0 +1,220 @@
+class ApiBlueprint::Compile::Compile
+  attr_reader :source, :target, :partials
+
+  def initialize(options)
+    @source = options[:source]
+    @target = options[:target]
+    @logger = options[:logger]
+
+    @partials = []
+  end
+
+  def compile
+    layout = load_layout
+    insert_content(layout)
+    insert_stylesheets(layout)
+
+    layout_html = layout.to_html
+    insert_javascripts(layout_html)
+
+    layout_doc = load_document(layout_html)
+    insert_title(layout_doc)
+    insert_host(layout_doc)
+    insert_copyright(layout_doc)
+
+    write_html(layout_doc.to_html)
+  end
+
+  private
+
+  def load_layout
+    log "Rendering '#{@source}' within the blueprint layout..."
+
+    Nokogiri::HTML(File.read(ApiBlueprint::Compile::Storage.index_html))
+  end
+
+  def load_document(html)
+    Nokogiri::HTML(html)
+  end
+
+  def write_html(layout_html)
+    return unless @target
+
+    File.write(@target, layout_html)
+
+    log "Wrote #{@title_text || "document"} into '#{@target}'"
+  end
+
+  def insert_content(layout)
+    container = layout.at_css("#blueprint-document")
+
+    if container
+      content = render_markdown(@source)
+      content = prepend_toc(content)
+
+      container.add_child(content)
+    end
+
+    log " - compiled #{(container/'h1').length} chapter(s)"
+  end
+
+  def insert_stylesheets(layout)
+    style = layout.at_css("#blueprint-style")
+
+    if style
+      text = ApiBlueprint::Compile::Storage.stylesheets.collect do |file|
+        Sass::Engine.new(File.read(file), :syntax => :scss, :style => :compressed).render
+      end.join("\n\n")
+
+      style.add_child(text)
+
+      log " - compiled #{ApiBlueprint::Compile::Storage.stylesheets.count} stylesheet(s)"
+    end
+  end
+
+  def insert_javascripts(layout_html)
+    return unless layout_html.include?('<script id="blueprint-script"></script>');
+
+    text = ApiBlueprint::Compile::Storage.javascripts.collect do |file|
+      Uglifier.compile(File.read(file))
+    end.join("\n\n")
+
+    layout_html.sub!('<script id="blueprint-script"></script>',
+      '<script id="blueprint-script">' + text + '</script>')
+
+    log " - compiled #{ApiBlueprint::Compile::Storage.stylesheets.count} javascript(s)"
+  end
+
+  def insert_title(doc)
+    title_node = doc.at('p:contains("Title: ")')
+
+    if title_node
+      @title_text = title_node.text.strip.sub("Title: ", '')
+      title_tag   = doc.at('title')
+
+      title_node['id'] = 'title'
+      title_node.content = @title_text
+
+      if title_tag
+        title_tag.content = @title_text
+      end
+    end
+  end
+
+  def insert_host(doc)
+    host_node = doc.at('p:contains("Host: ")')
+
+    if host_node
+      @host_text = host_node.text.strip.sub("Host: ", '')
+
+      host_node['id'] = 'host'
+      host_node.content = @host_text
+    end
+  end
+
+  def insert_copyright(doc)
+    copyright_node = doc.at('p:contains("Copyright: ")')
+
+    if copyright_node
+      copyright_text = copyright_node.text.strip.sub("Copyright: ", '')
+      copyright_text = "© #{Date.today.year} #{copyright_text}"
+      copyright_tag  = doc.at('.copyright')
+
+      copyright_node['id'] = 'copyright'
+      copyright_node.content = copyright_text
+
+      if copyright_tag
+        copyright_tag.content = copyright_text
+      end
+    end
+  end
+
+  def render_markdown(input_file)
+    markdown  = Redcarpet::Markdown.new(Redcarpet::Render::HTML, :tables => true, :no_intra_emphasis => true)
+    content   = markdown.render(File.read(input_file))
+    doc       = Nokogiri::HTML(content)
+    requires  = (doc/'a:contains("require:")')
+
+    requires.each do |require_link|
+      file = require_link['href'].split(':').last
+      file = input_file.split('/')[0..-2].join('/') + '/' + file + '.md'
+      file = render_markdown(file)
+
+      require_link.after(file)
+      require_link.remove
+    end
+
+    partials << input_file unless partials.include?(input_file)
+
+    doc.to_html
+  end
+
+  def prepend_toc(doc)
+    doc = Nokogiri::HTML(doc)
+    headers = []
+
+    (doc/"h1").each_with_index do |header, header_index|
+      subheaders = []
+      header['id'] = header.text.sub('Resource: ', '').parameterize
+      headers << { :title => header.text.sub('Resource: ', ''), :id => header['id'], :subheaders => subheaders }
+
+      next_all(header, :where => "h2", :until => 'h1').each_with_index do |action_header, action_index|
+        action_header['id'] = header['id'] + "-" + action_header.text.sub('Action: ', '').parameterize
+        subheaders << { :title => action_header.text.sub('Action: ', ''), :id => action_header['id'] }
+      end
+    end
+
+    toc = "<h1>Table Of Contents</h1>"
+    toc += "<ul>"
+
+    headers.collect do |header|
+      toc += "<li>"
+      toc += "<a href='##{header[:id]}'>#{header[:title]}</a>"
+
+      if header[:subheaders].any?
+        toc += "<ul>"
+        header[:subheaders].each do |subheader|
+          toc += "<li><a href='##{subheader[:id]}'>#{subheader[:title]}</a></li>"
+        end
+        toc += "</ul>"
+      end
+
+      toc += '</li>'
+    end
+
+    toc += "</ul>"
+
+    doc.at('h1').before(toc)
+
+    doc.to_html
+  end
+
+  def next_all(element, options = {})
+    doc = element.document
+
+    selector = options[:where]
+    rejector = options[:until]
+    results  = Nokogiri::XML::NodeSet.new(doc)
+    element  = element.next_element
+
+    while element
+      set = Nokogiri::XML::NodeSet.new(doc, [element])
+
+      if rejector && (set/rejector).any?
+        break
+      elsif ! selector || (set/selector).any?
+        results << element
+      end
+
+      element = element.next_element
+    end
+
+    return results
+  end
+
+  def log(message)
+    if @logger.to_s == 'stdout'
+      puts message
+    end
+  end
+end

data/lib/api_blueprint/compile/storage.rb

@@ -0,0 +1,17 @@
+module ApiBlueprint::Compile::Storage
+  def self.root_join(*parts)
+    File.join(File.dirname(__FILE__), *parts)
+  end
+
+  def self.index_html
+    root_join('assets', 'index.html')
+  end
+
+  def self.javascripts
+    Dir[root_join('assets', '*.js').to_s]
+  end
+
+  def self.stylesheets
+    Dir[root_join('assets', '*.scss').to_s]
+  end
+end

data/lib/api_blueprint/railtie.rb

@@ -0,0 +1,15 @@
+module ApiBlueprint
+  class Railtie < Rails::Railtie
+    railtie_name :api_blueprint
+
+    initializer "api_blueprint.action_controller" do
+      ActiveSupport.on_load(:action_controller) do
+        include ApiBlueprint::Collect::ControllerHook
+      end
+    end
+
+    rake_tasks do
+      load 'tasks/blueprint.rake'
+    end
+  end
+end

data/lib/api_blueprint/version.rb

@@ -0,0 +1,3 @@
+module ApiBlueprint
+  VERSION = '0.1.0'
+end

data/lib/api_blueprint.rb

@@ -0,0 +1,16 @@
+module ApiBlueprint
+  Collect = Module.new
+  Compile = Module.new
+end
+
+require 'redcarpet'
+require 'api_blueprint/collect/controller_hook'
+require 'api_blueprint/collect/merge'
+require 'api_blueprint/collect/preprocessor'
+require 'api_blueprint/collect/renderer'
+require 'api_blueprint/collect/spec_hook'
+require 'api_blueprint/collect/storage'
+require 'api_blueprint/compile/compile'
+require 'api_blueprint/compile/storage'
+require 'api_blueprint/railtie'
+require 'api_blueprint/version'

data/lib/tasks/blueprint.rake

@@ -0,0 +1,140 @@
+def blueprintfile(opts = {})
+  file = Rails.root.join("Blueprintfile")
+
+  if File.exists?(file)
+    file = YAML.load_file(file)
+
+    if ENV['group']
+      hash = file[ENV['group']] || {}
+    else
+      hash = file.any? ? file.first[1] : {}
+    end
+  else
+    hash = {}
+  end
+
+  if opts[:write_blueprint] != false && hash['blueprint'].present? && File.exists?(hash['blueprint'])
+    hash.delete('blueprint')
+  end
+
+  ['spec', 'blueprint', 'html'].each do |param|
+    hash[param] = ENV[param] if ENV[param].present?
+  end
+
+  hash
+end
+
+def compile(source, target)
+  compiler = ApiBlueprint::Compile::Compile.new(:source => source, :target => target, :logger => :stdout)
+  compiler.compile
+
+  compiler
+end
+
+def regenerate_dumps
+  Rake::Task["blueprint:collect:clear"].execute
+  puts
+  Rake::Task["blueprint:collect:generate"].execute
+  puts
+end
+
+namespace :blueprint do
+  desc 'Clear, generate and merge dumps for specified request spec(s)'
+  task :collect => :environment do
+    regenerate_dumps
+
+    Rake::Task["blueprint:collect:merge"].execute
+  end
+
+  namespace :collect do
+    desc 'Remove all generated request dumps'
+    task :clear => :environment do
+      files = ApiBlueprint::Collect::Storage.request_dumps
+
+      puts "Clearing #{files.count} request dumps..."
+
+      File.unlink(*files)
+    end
+
+    desc 'Generate request dumps for specified request spec(s)'
+    task :generate => :environment do
+      args = blueprintfile['spec'] || "spec/requests/#{ENV['group'] || 'api'}"
+      opts = { :order => 'default', :format => 'documentation' }
+      cmd  = "API_BLUEPRINT_DUMP=1 bundle exec rspec #{opts.map{|k,v| "--#{k} #{v}"}.join(' ')} #{args}"
+
+      puts "Invoking '#{cmd}'..."
+
+      system(cmd)
+    end
+
+    desc 'Merge all existing request dumps into single blueprint'
+    task :merge => :environment do
+      target = blueprintfile['blueprint'] || Rails.root.join('tmp', 'merge.md')
+
+      ApiBlueprint::Collect::Merge.new(:target => target, :logger => :stdout, :naming => blueprintfile['naming']).merge
+    end
+  end
+
+  namespace :examples do
+    desc 'Clear existing examples in blueprint'
+    task :clear => :environment do
+      target = blueprintfile(:write_blueprint => false)['blueprint'] || Rails.root.join('tmp', 'merge.md')
+
+      ApiBlueprint::Collect::Merge.new(:target => target, :logger => :stdout).clear_examples
+    end
+
+    desc 'Uuse dumps to update examples in blueprint'
+    task :update => :environment do
+      target = blueprintfile(:write_blueprint => false)['blueprint'] || Rails.root.join('tmp', 'merge.md')
+
+      ApiBlueprint::Collect::Merge.new(:target => target, :logger => :stdout).update_examples
+    end
+
+    desc 'Use dumps to replace examples in blueprint'
+    task :replace => :environment do
+      target = blueprintfile(:write_blueprint => false)['blueprint'] || Rails.root.join('tmp', 'merge.md')
+
+      ApiBlueprint::Collect::Merge.new(:target => target, :logger => :stdout).clear_examples
+      ApiBlueprint::Collect::Merge.new(:target => target, :logger => :stdout).update_examples
+    end
+  end
+
+  desc 'Compile the blueprint into complete HTML documentation'
+  task :compile => :environment do
+    source = blueprintfile(:write_blueprint => false)['blueprint'] || Rails.root.join('tmp', 'merge.md')
+    target = blueprintfile(:write_blueprint => false)['html'] || source.to_s.sub(/\.md$/, '.html')
+
+    compile(source, target)
+  end
+
+  desc 'Watch for changes in the blueprint and compile it into HTML on every change'
+  task :watch => :environment do
+    source = blueprintfile(:write_blueprint => false)['blueprint'] || Rails.root.join('tmp', 'merge.md')
+    target = blueprintfile(:write_blueprint => false)['html'] || source.to_s.sub(/\.md$/, '.html')
+
+    files = compile(source, target).partials
+
+    FileWatcher.new(files).watch do |filename|
+      puts "\n--- #{Time.now} [#{filename.split('/').last}] ---\n\n"
+      compile(source, target)
+    end
+  end
+
+  desc 'Deploy the HTML documentation on remote target'
+  task :deploy => :environment do
+    Rake::Task["blueprint:compile"].execute
+
+    source = blueprintfile(:write_blueprint => false)['html']
+    target = blueprintfile(:write_blueprint => false)['deploy']
+
+    if source.present? && target.present?
+      cmd = "scp -q #{source} #{target}"
+
+      puts "\nDeploying to '#{target}'..."
+
+      system(cmd)
+    end
+  end
+end
+
+

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: api_blueprint
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Karol Słuszniak
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-10-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: filewatcher
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: You start with method list generated from RSpec request specs. For each
+  method, you get a list of parameters and examples. Then, you can extend it in whatever
+  way you need using Markdown syntax. You can organize documentation files into partials.
+  Upon any API change, like serializer change that changes responses, you can update
+  automatically generated parts of docs. Once done, you can compile your documentation
+  into single, nicely styled HTML file. You can also auto-deploy it via SSH.
+email: k.sluszniak@visuality.pl
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/api_blueprint.rb
+- lib/api_blueprint/collect/controller_hook.rb
+- lib/api_blueprint/collect/merge.rb
+- lib/api_blueprint/collect/preprocessor.rb
+- lib/api_blueprint/collect/renderer.rb
+- lib/api_blueprint/collect/spec_hook.rb
+- lib/api_blueprint/collect/storage.rb
+- lib/api_blueprint/compile/compile.rb
+- lib/api_blueprint/compile/storage.rb
+- lib/api_blueprint/railtie.rb
+- lib/api_blueprint/version.rb
+- lib/tasks/blueprint.rake
+homepage: http://github.com/visualitypl/api-blueprint
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Semi-automatic solution for creating Rails app's API documentation based
+  on RSpec request specs.
+test_files: []