rocket_docs 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 97e8e49ad6cf5ad899dd4e256ea5ef36e34f259b
+  data.tar.gz: 4b7ed20c4cdb13d88576684948e01d903be40665
+SHA512:
+  metadata.gz: c5c728791f5e8e6d2590e0fac023314a962c2b2fa211d2b6bd1ecd9b0087430a430e3d2337cfe35c449104bb0ed0ca3587847d5230b1974c36d2c501ac28b51b
+  data.tar.gz: dbd9b9939b76bcf4a00c14b8b775a66e0fdbd5062be68a96f5125545f5cd285d6e1cc27af65cfb033c9a379d353324eecd0993774734a83474ffb493caf75fcd

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2015 YOURNAME
+
+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/Rakefile

@@ -0,0 +1,24 @@
+begin
+  require 'rubygems'
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'RocketDocs'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path('../spec/test_app/Rakefile', __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+
+RSpec::Core::RakeTask.new(:spec)
+task default: :appraisal if !ENV['APPRAISAL_INITIALIZED'] && !ENV['TRAVIS']

data/app/assets/javascripts/rocket_docs/application.js

@@ -0,0 +1,206 @@
+//= require jquery
+//= require jquery_ujs
+//= require bootstrap
+
+$(document).ready(function () {
+  $('#try-out-modal').on('show.bs.modal', function (event) {
+    var $modal = $(this);
+    var $triggerButton = $(event.relatedTarget);
+    var $testButton = $modal.find('.btn.try');
+    $modal.find('h4.modal-title').text('' +
+      $triggerButton.data('request-method') + ' ' + $triggerButton.data('url')
+    );
+    $modal.find('.modal-body').html(
+      contentForModal(
+        $triggerButton.data('url'),
+        $triggerButton.data('request-method'),
+        $triggerButton.data('params'),
+        $triggerButton.data('saved_params'),
+        $triggerButton.data('saved_text')
+      )
+    );
+    $testButton.click(function(){
+      saveParams($modal.find('.modal-body'), $triggerButton);
+      var $response = $modal.find('.response');
+
+      $modal.find('.response-body').removeClass('hidden');
+      addSpinner($response);
+
+      $.ajax(
+        buildRequestParams($modal.find('.modal-body'), $triggerButton.data('url'), $triggerButton.data('request-method'))
+      ).done(function(data, textStatus, jqXHR) {
+        var response = jqXHR.responseText;
+
+        $response.html('');
+        $response.text(response);
+        $(window).trigger('resize');
+      });
+    });
+  }).on('hidden.bs.modal', function () {
+    var $modal = $(this);
+    $modal.find('h4.modal-title').text('Try it');
+    $modal.find('.modal-body').html('');
+  });
+
+  function buildRequestParams($object, url, method) {
+    var $inputs = $object.find('input[data-key]');
+    var $requestBody = $object.find('textarea');
+    var data = null;
+    var processData = true;
+
+    if ($inputs.length !== 0) {
+      data = {};
+      $inputs.each(function(i, $input) {
+        $input = $($input);
+        if (url.indexOf('{' + $input.data('key') + '}')) {
+          url = url.replace('{' + $input.data('key') + '}', $input.val());
+        } else {
+          data[$input.data('key')] = $input.val();
+        }
+      });
+    }
+    if ($requestBody.length !== 0) {
+      processData = false;
+      data = $requestBody.val();
+    }
+
+    return {
+      url: url,
+      type: method,
+      processData: processData,
+      data: data
+    };
+  }
+
+  function saveParams($object, $saveToObject) {
+    var $inputs = $object.find('input[data-key]');
+    var $requestBody = $object.find('textarea');
+
+    if ($inputs.length !== 0) {
+      var params = {};
+      $inputs.each(function(i, $input) {
+        $input = $($input);
+        params[$input.data('key')] = $input.val();
+      });
+      $saveToObject.data('saved_params', params);
+    }
+
+    if ($requestBody.length !== 0) {
+      $saveToObject.data('saved_text', $requestBody.val());
+    }
+
+    return true;
+  }
+
+  function addSpinner($object) {
+      var message = '<center>'+
+                      '<span class="glyphicon glyphicon-refresh gly-spin"></span>'+
+                      '  Waiting for response...'+
+                    '</center>';
+      $object.html(message);
+  }
+
+  function contentForModal(url, method, params, savedParams, savedText) {
+    var content = '';
+    content += '<h3>Request body</h3>';
+    if (method === 'GET' && params) {
+      content += paramsInputTable(params, savedParams);
+    } else {
+      var regex = /\{[^\s]+\}/;
+      var match = regex.exec(url);
+      if (match && match.length !== 0) {
+        var tempParams = {};
+        $.each(match, function(i, m) {
+          tempParams[m.replace(/[\{\}]/g,'')] = i;
+        });
+        content += paramsInputTable(tempParams, savedParams);
+      }
+      var saved = '';
+      if (savedText) {
+        saved = savedText;
+      }
+      content += '<textarea class="form-control" rows="6" cols="90">' + saved + '</textarea>';
+    }
+    if (method !== 'GET' && params) {
+      content += '<h4>Expected params</h4>';
+      content += paramsTable(params);
+    }
+    content += '<div class="response-body hidden">';
+    content += '<hr>';
+    content += '<h3>Response</h3>';
+    content += '<pre><code class="response"></code></pre>';
+    content += '</div>';
+
+    return content;
+  }
+
+  function paramsInputTable(params, savedParams) {
+    var content  = '<table class="table table-striped">';
+    content += '<thead>';
+    content += '<tr>'+
+                 '<th>Param</th>'+
+                 '<th>Value</th>'+
+               '</tr>';
+    content += '</thead>';
+    $.each(params, function(k, v) {
+      content += paramsInputTableRow(k, v, null, savedParams);
+    });
+    content += '</table>';
+    return content;
+  }
+
+  function paramsInputTableRow(k, v, wrapper, savedParams) {
+    var content = '';
+    var saved = '';
+    if (wrapper) {
+      k = wrapper + '[' + k + ']';
+    }
+    if (savedParams && savedParams[k]) {
+      saved = savedParams[k];
+    }
+    if (typeof v === 'object') {
+      $.each(v, function(kk, vv) {
+        content += paramsInputTableRow(kk, vv, k, savedParams);
+      });
+    } else {
+      content += '<tr>'+
+                   '<td>' + k + '</td>'+
+                   '<td><input type="text" class="form-control" value="' + saved + '" data-key="' + k + '"></td>'+
+                 '</tr>';
+    }
+    return content;
+  }
+
+  function paramsTable(params) {
+    var content  = '<table class="table table-striped">';
+    content += '<thead>';
+    content += '<tr>'+
+                 '<th>Name</th>'+
+                 '<th>Type</th>'+
+               '</tr>';
+    content += '</thead>';
+    $.each(params, function(k, v){
+      content += paramsTableRow(k, v, null);
+    });
+    content += '</table>';
+    return content;
+  }
+
+  function paramsTableRow(k, v, wrapper) {
+    var content = '';
+    if (wrapper) {
+      k = wrapper + '[' + k + ']';
+    }
+    if (typeof v === 'object') {
+      $.each(v, function(kk, vv) {
+        content += paramsTableRow(kk, vv, k);
+      });
+    } else {
+      content += '<tr>'+
+                   '<td>' + k + '</td>'+
+                   '<td>' + v + '</td>'+
+                 '</tr>';
+    }
+    return content;
+  }
+});

data/app/assets/stylesheets/rocket_docs/application.scss

@@ -0,0 +1,51 @@
+/*
+ *= require_tree .
+ *= require_self
+ */
+ @import "bootstrap-sprockets";
+ @import "bootstrap";
+
+body {
+  padding-top: 70px;
+}
+
+.gly-spin {
+  -webkit-animation: spin 2s infinite linear;
+  -moz-animation: spin 2s infinite linear;
+  -o-animation: spin 2s infinite linear;
+  animation: spin 2s infinite linear;
+}
+@-moz-keyframes spin {
+  0% {
+    -moz-transform: rotate(0deg);
+  }
+  100% {
+    -moz-transform: rotate(359deg);
+  }
+}
+@-webkit-keyframes spin {
+  0% {
+    -webkit-transform: rotate(0deg);
+  }
+  100% {
+    -webkit-transform: rotate(359deg);
+  }
+}
+@-o-keyframes spin {
+  0% {
+    -o-transform: rotate(0deg);
+  }
+  100% {
+    -o-transform: rotate(359deg);
+  }
+}
+@keyframes spin {
+  0% {
+    -webkit-transform: rotate(0deg);
+    transform: rotate(0deg);
+  }
+  100% {
+    -webkit-transform: rotate(359deg);
+    transform: rotate(359deg);
+  }
+}

data/app/controllers/rocket_docs/application_controller.rb

@@ -0,0 +1,13 @@
+module RocketDocs
+  class ApplicationController < ActionController::Base
+    def index
+      @docs = RocketDocs.documentation
+      render 'docs/rocket_docs/index'
+    end
+
+    def show
+      @doc = RocketDocs.documentation_for_version(params[:version])
+      render 'docs/rocket_docs/show'
+    end
+  end
+end

data/app/helpers/rocket_docs/application_helper.rb

@@ -0,0 +1,24 @@
+module RocketDocs
+  module ApplicationHelper
+    def doc_id(doc)
+      "version_#{web_safe(doc.version)}"
+    end
+
+    def controller_id(controller)
+      "#{doc_id(controller.documentation)}_controller_"\
+      "#{web_safe(controller.name)}"
+    end
+
+    def action_id(action)
+      "#{controller_id(action.controller)}_action_#{web_safe(action.name)}"
+    end
+
+    def method_id(action, method)
+      "#{action_id(action)}_method_#{web_safe(method)}"
+    end
+
+    def web_safe(string)
+      string.to_s.humanize.sub(' ', '').underscore
+    end
+  end
+end

data/app/views/docs/rocket_docs/_action.markdown.erb

@@ -0,0 +1,23 @@
+### <%= action.name %>
+
+<% action.methods.each do |method| %>
+#### <%= method.upcase %>
+
+> __URL:__ <%= '' || action.url %>
+
+<% if action.description(method) %>
+>__DESCRIPTION:__ <%= action.description(method) %>
+<% end %>
+
+<% if action.params(method) %>
+>__PARAMS:__
+
+>| Name | Type |
+>| ---- | ---- |
+<% action.params(method).each do |k, v| %>
+>| <%= k %> | <%= v %> |
+<% end %>
+<% end %>
+
+
+<% end %>

data/app/views/docs/rocket_docs/_action.slim

@@ -0,0 +1,43 @@
+.panel.panel-default
+  .panel-heading
+    h4.panel-title
+      = link_to "#{action.name}", "##{action_id(action)}", data: { toggle: 'collapse' }
+  .panel-collapse.collapse id="#{action_id(action)}"
+    .panel-body
+      ul.nav.nav-tabs
+        - action.methods.each_with_index do |method, index|
+          li class="#{index == 0 ? 'active' : ''}"
+            = link_to method.upcase, "##{method_id(action, method)}", data: { toggle: 'tab' }
+      .tab-content
+        - action.methods.each_with_index do |method, index|
+            .tab-pane class="#{index == 0 ? 'active' : ''}" id="#{method_id(action, method)}"
+
+              .col-md-6
+                .row
+                  .col-xs-12
+                    - if action.url(method)
+                      h4 URL
+                      = action.url
+                  .col-xs-12
+                    - if action.description(method)
+                      h4 Description
+                      = simple_format(action.description(method))
+              .col-md-6
+                .row
+                  .col-xs-12
+                    - if action.params(method)
+                      h4 Params
+                      table.table.table-striped
+                        thead
+                          tr
+                            th Name
+                            th Type
+                        tbody
+                          = render 'docs/rocket_docs/hash_param', hash: action.params(method), wrap: nil
+
+              - if action.url(method)
+                .col-xs-12
+                  hr
+                  = link_to '#', class: 'btn btn-primary try-out', data: { request_method: method, params: action.params(method), url: action.url, toggle: 'modal', target: '#try-out-modal' } do
+                    span.glyphicon.glyphicon-new-window
+                    |  Try it out

data/app/views/docs/rocket_docs/_controller.markdown.erb

@@ -0,0 +1,7 @@
+## <%= controller.name %>
+
+<% controller.actions.each do |action| %>
+<%= render 'docs/rocket_docs/action.markdown.erb', action: action %>
+
+___
+<% end %>

data/app/views/docs/rocket_docs/_controller.slim

@@ -0,0 +1,9 @@
+.panel.panel-default
+  .panel-heading
+    h4.panel-title
+      = link_to "#{controller.name}", "##{controller_id(controller)}", data: { toggle: 'collapse' }
+  .panel-collapse.collapse id="#{controller_id(controller)}"
+    .panel-body
+      .panel-group id="#{controller_id(controller)}_accordion"
+        - controller.actions.each do |action|
+          = render 'docs/rocket_docs/action', action: action

data/app/views/docs/rocket_docs/_documentation.markdown.erb

@@ -0,0 +1,4 @@
+<% doc.controllers.each do |controller| %>
+<%= render 'docs/rocket_docs/controller.markdown.erb', controller: controller %>
+
+<% end %>

data/app/views/docs/rocket_docs/_documentation.slim

@@ -0,0 +1,3 @@
+.panel-group id="#{doc_id(doc)}_accordion"
+  - doc.controllers.each do |controller|
+      = render 'docs/rocket_docs/controller', controller: controller

data/app/views/docs/rocket_docs/_hash_param.slim

@@ -0,0 +1,7 @@
+- hash.each do |k, v|
+  - if v.is_a?(Hash)
+    = render 'docs/rocket_docs/hash_param', hash: v, wrap: wrap ? "#{wrap}[#{k}]" : k
+  - else
+    tr
+      td = wrap ? "#{wrap}[#{k}]" : k
+      td = v

data/app/views/docs/rocket_docs/_version.slim

@@ -0,0 +1,7 @@
+.panel.panel-default
+  .panel-heading
+    h4.panel-title
+      = link_to "Version #{doc.version}", "##{doc_id(doc)}", data: { toggle: 'collapse' }
+  .panel-collapse.collapse id="#{doc_id(doc)}"
+    .panel-body
+      = render 'docs/rocket_docs/documentation', doc: doc

data/app/views/docs/rocket_docs/index.slim

@@ -0,0 +1,3 @@
+.panel-group#versions_accordion
+  - @docs.each do |doc|
+    = render 'docs/rocket_docs/version', doc: doc

data/app/views/docs/rocket_docs/show.markdown.erb

@@ -0,0 +1,3 @@
+# <%= @doc.version %>
+
+<%= render 'docs/rocket_docs/documentation.markdown.erb', doc: @doc %>

data/app/views/docs/rocket_docs/show.slim

@@ -0,0 +1,4 @@
+h1= @doc.version
+hr
+.col-xs-12
+  = render 'docs/rocket_docs/documentation', doc: @doc

data/app/views/layouts/rocket_docs/_modal.slim

@@ -0,0 +1,12 @@
+.modal.fade#try-out-modal
+  .modal-dialog
+    .modal-content
+      .modal-header
+        button.close data-dismiss='modal'
+        h4.modal-title Try it
+      .modal-body
+      .modal-footer
+        button.btn.btn-default data-dismiss='modal'
+          | Close
+        button.btn.btn-primary.try
+          | Try it

data/app/views/layouts/rocket_docs/_navigation.slim

@@ -0,0 +1,10 @@
+- if defined?(rocket_docs)
+  .navbar.navbar-default.navbar-fixed-top
+    .container-fluid
+      .navbar-header
+        = link_to 'Documentation', rocket_docs.root_path, class: 'navbar-brand'
+      .collapse.navbar-collapse
+        ul.nav.navbar-nav
+          li = link_to 'All versions', rocket_docs.root_path
+          - RocketDocs::Router.versions.each do |v|
+            li = link_to v.to_s, rocket_docs.version_path(version: v)

data/app/views/layouts/rocket_docs/application.slim

@@ -0,0 +1,9 @@
+head
+  title RocketDocs
+  = stylesheet_link_tag    "rocket_docs/application", media: "all"
+  = javascript_include_tag "rocket_docs/application"
+body
+  = render 'layouts/rocket_docs/navigation'
+  .container
+    = yield
+  = render 'layouts/rocket_docs/modal'

data/config/routes.rb

@@ -0,0 +1,5 @@
+RocketDocs::Engine.routes.draw do
+  root 'application#index'
+  get 'versions', to: 'application#index', as: 'versions'
+  get 'version/:version', to: 'application#show', as: 'version'
+end

data/lib/rocket_docs/documentation/action.rb

@@ -0,0 +1,98 @@
+module RocketDocs
+  class Documentation
+    class Action
+      attr_reader :name
+      attr_reader :controller
+      attr_reader :comments
+
+      def initialize(name, comments, methods, params, controller)
+        @name = name
+        @comments = comments
+        @methods = sanitize_methods(methods)
+        @params  = params
+        @params.delete(:version) if params
+        @params = @params.presence
+        @controller = controller
+        generate
+      end
+
+      def url(method = default_method)
+        (@doc[method] && @doc[method]['URL']) || @doc['URL'] ||
+          router_url(method)
+      end
+
+      def description(method = default_method)
+        desc = (@doc[method] && @doc[method]['DOC']) || @doc['DOC']
+        desc && CGI.escapeHTML(desc).gsub("\n", '<br>').html_safe
+      end
+
+      def params(method = default_method)
+        (@doc[method] && @doc[method]['PARAMS']) || @doc['PARAMS'] ||
+          @params
+      end
+
+      def default_method
+        methods.first || 'GET'
+      end
+
+      def methods
+        @methods.presence ||
+          @doc.keys.select { |m| Parser.http_keywords.include?(m) }
+      end
+
+      private
+
+      def generate
+        return @doc = {} unless @comments.present?
+        @doc = RocketDocs::Parser.parse_comments(@comments).value
+      end
+
+      def _routes
+        RocketDocs::Router.app_routes
+      end
+
+      def sanitize_methods(methods)
+        return unless methods
+        methods.map do |m|
+          if m.is_a?(String)
+            m
+          else
+            m.to_s.sub('(?-mix:^', '').sub('$)', '').split('|')
+          end
+        end.flatten
+      end
+
+      def router_url(method = default_method)
+        route = _routes.url_for(url_params(method))
+        route = route.split('?').first unless method == 'GET'
+        CGI.unescape(route)
+      rescue ActionController::UrlGenerationError
+        nil
+      end
+
+      def url_params(method = default_method)
+        hash = {}
+        hash = deflated_url_params(params(method)) if @params
+        hash.merge(
+          controller: controller.full_name.downcase,
+          action: name,
+          version: controller.documentation.version,
+          only_path: true
+        )
+      end
+
+      def deflated_url_params(hash, wrapper = nil)
+        nh = {}
+        hash.each do |k, v|
+          new_v = wrapper ? "#{wrapper}[#{k}]" : k
+          if v.is_a?(Hash)
+            nh[k] = deflated_url_params(v, k)
+          else
+            nh[k] = "{#{new_v}}"
+          end
+        end
+        nh.symbolize_keys
+      end
+    end
+  end
+end

data/lib/rocket_docs/documentation/controller.rb

@@ -0,0 +1,57 @@
+module RocketDocs
+  class Documentation
+    class Controller
+      attr_accessor :name
+      attr_accessor :file
+      attr_reader :documentation
+      attr_reader :actions
+
+      def initialize(name, file, actions_hash, documentation)
+        @file_md5  = ''
+        @actions = []
+        @actions_in = actions_hash
+        self.name = name
+        self.file = file
+        @documentation = documentation
+        update!
+      end
+
+      def update
+        should_update? && update!
+      end
+
+      def update!
+        @file_md5 = generate_hash
+        generate
+      end
+
+      def should_update?
+        return false if generate_hash == @file_md5
+        true
+      end
+
+      def name
+        return unless @name
+        @name.split('/').last.sub('_controller', '').humanize
+      end
+
+      def full_name
+        @name
+      end
+
+      private
+
+      def generate
+        @actions = []
+        comments = RocketDocs::Parser.method_comments(file)
+        @actions_in.each do |name, action|
+          @actions << Action.new(name, comments[name], action[:methods], action[:params], self)
+        end
+      end
+
+      def generate_hash
+        Digest::MD5.file(file).hexdigest
+      end
+    end
+  end
+end