rocket_docs 0.0.2

data/lib/rocket_docs/documentation.rb

@@ -0,0 +1,46 @@
+require 'rocket_docs/documentation/controller'
+require 'rocket_docs/documentation/action'
+
+module RocketDocs
+  class Documentation
+    attr_reader :version
+    attr_reader :controllers
+
+    def initialize(version, controllers_hash)
+      @version = version
+      @controllers = []
+      @controllers_in = controllers_hash
+      generate
+    end
+
+    def should_update?
+      should_update = false
+      controllers.each { |c| should_update ||= c.should_update? }
+      should_update
+    end
+
+    def update
+      controllers.each(&:update)
+      self
+    end
+
+    def update!
+      controllers.each(&:update!)
+      self
+    end
+
+    private
+
+    def generate
+      build_controllers
+      update
+    end
+
+    def build_controllers
+      @controllers = []
+      @controllers_in.each do |n, v|
+        @controllers << Controller.new(n, v[:path], v[:actions], self)
+      end
+    end
+  end
+end

data/lib/rocket_docs/engine.rb

@@ -0,0 +1,12 @@
+module RocketDocs
+  class Engine < ::Rails::Engine
+    isolate_namespace RocketDocs
+    require 'jquery-rails'
+    require 'bootstrap-sass'
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.fixture_replacement :factory_girl, dir: 'spec/factories'
+    end
+  end
+end

data/lib/rocket_docs/parser.rb

@@ -0,0 +1,105 @@
+module RocketDocs
+  module Parser
+    class << self
+      def comments_for_method(method_name, file_path)
+        method_comments(file_path)[method_name.to_s]
+      end
+
+      def method_comments(file_path)
+        comments = {}
+        temp_comment = []
+        File.read(file_path).each_line do |line|
+          if extract_method_comment(line, comments, temp_comment)
+            temp_comment = []
+          end
+        end
+        clean_comments(comments)
+      end
+
+      def parse_comments(comments)
+        indentation_parser.read(comments, {})
+      end
+
+      def keywords
+        http_keywords + parser_keywords
+      end
+
+      def http_keywords
+        %w(GET POST PUT PATCH DELETE)
+      end
+
+      def parser_keywords
+        string_keywords + hash_keywords
+      end
+
+      private
+
+      def string_keywords
+        %w(DOC URL)
+      end
+
+      def hash_keywords
+        %w(PARAMS)
+      end
+
+      def indentation_parser
+        IndentationParser.new do |p|
+          indentation_parser_default(p)
+          indentation_parser_leafs(p)
+        end
+      end
+
+      def indentation_parser_default(p)
+        p.default do |parent, source|
+          parent ||= {}
+          words = source.split
+          keyword, key = words.first.upcase, words.first
+          if words.count == 1 && keywords.include?(keyword)
+            parent[keyword] = string_keywords.include?(keyword) ? '' : {}
+          elsif words.count == 1 && parent.is_a?(Hash)
+            parent[key] = {}
+          end
+        end
+      end
+
+      def indentation_parser_leafs(p)
+        p.on_leaf do |parent, source|
+          case parent
+          when String
+            parent << "\n" if parent.length != 0
+            parent << source.try(:strip) || ''
+          when Hash
+            k, v = source.split(':', 2)
+            parent[k] = v ? v.try(:strip) : {}
+          end
+        end
+      end
+
+      def extract_method_comment(line, comments = {}, temp_comment = [])
+        return true unless valid_line?(line)
+        if line =~ /^\s*def\s+\w+$/
+          comments[method_name(line)] = temp_comment.join("\n")
+          true
+        else
+          temp_comment << line
+          false
+        end
+      end
+
+      def valid_line?(line)
+        line =~ /^\s*#.*$/ || line =~ /^\s*def\s+\w+$/ || line =~ /^\s+$/
+      end
+
+      def method_name(line)
+        line.match(/^\s*def\s+\w+$/).to_s.split(' ').last
+      end
+
+      def clean_comments(comments)
+        comments.each do |k, v|
+          comments[k] = v.gsub(/^\s*#\s?/, '').gsub(/\n+/, "\n")
+        end
+        comments
+      end
+    end
+  end
+end

data/lib/rocket_docs/router.rb

@@ -0,0 +1,86 @@
+module RocketDocs
+  module Router
+    class << self
+      def api_full
+        result = {}
+        versions.each { |v| result[v] = {} }
+        result.each { |k, v| fill_controllers_hash_for_version(k, v) }
+        result
+      end
+
+      def api_controller_paths(controllers = api_controllers)
+        cp = controllers.map do |c|
+          c.instance_methods(false).map do |m|
+            c.instance_method(m).source_location.first
+          end
+        end
+        cp.flatten.uniq.compact
+      end
+
+      def api_controllers(names = api_controller_names)
+        names.map do |cn|
+          cn += '_controller'
+          cn.classify.constantize
+        end
+      end
+
+      def api_controller_names
+        ar = routes.named_routes.select { |_k, v| v.defaults[:rp_prefix] }
+        ar.values.map { |r| r.defaults[:controller] }.uniq
+      end
+
+      def routes_for_version(version)
+        routes.to_a.select { |v| v && v.defaults[:version] == version }
+      end
+
+      def versions
+        routes.to_a.map { |r| r && r.defaults[:version] }.uniq.compact
+      end
+
+      def routes
+        app_routes.routes
+      end
+
+      def app_routes
+        Rails.application.class.routes
+      end
+
+      private
+
+      def fill_controllers_hash_for_version(version, hash)
+        routes = routes_for_version(version)
+        routes.each do |r|
+          route_controller(hash, r)
+        end
+      end
+
+      def route_controller(ch, r)
+        cn = r.defaults[:controller]
+        ch[cn] ||= {}
+        ch[cn][:path] ||= api_controller_paths(api_controllers([cn])).first
+        ch[cn][:actions] ||= {}
+        route_action(ch[cn][:actions], r)
+      end
+
+      def route_action(hash, r)
+        ah = hash[r.defaults[:action]] ||= {}
+        ah[:params] = route_params(r)
+        route_methods(ah, r)
+      end
+
+      def route_params(r)
+        Hash[
+          r.required_parts.map do |name|
+            type = r.constraints[name.to_sym] || '???'
+            [name, type]
+          end
+        ]
+      end
+
+      def route_methods(hash, r)
+        hash[:methods] ||= []
+        hash[:methods] << r.constraints[:request_method]
+      end
+    end
+  end
+end

data/lib/rocket_docs/version.rb

@@ -0,0 +1,3 @@
+module RocketDocs
+  VERSION = '0.0.2'
+end

data/lib/rocket_docs.rb

@@ -0,0 +1,30 @@
+require 'pry'
+require 'slim'
+require 'indentation-parser'
+require 'rocket_docs/engine'
+require 'rocket_docs/router'
+require 'rocket_docs/parser'
+require 'rocket_docs/documentation'
+
+module RocketDocs
+  def self.documentation
+    Router.api_full.map do |version, controller|
+      Documentation.new(version, controller)
+    end
+  end
+
+  def self.documentation_for_version(version)
+    Documentation.new(version, Router.api_full[version])
+  end
+
+  def self.documentation_for_files(files, version_name = 'Unknown')
+    fake_controlers = files.map do |file|
+      fake_controller = {
+        path: file,
+        actions: Hash[Parser.method_comments(file).keys.map { |m, _c| [m, []] }]
+      }
+      [File.basename(file, '.rb'), fake_controller]
+    end
+    Documentation.new(version_name, Hash[fake_controlers])
+  end
+end

data/lib/tasks/rocket_docs_tasks.rake

@@ -0,0 +1,85 @@
+namespace :rocket_docs do
+  desc 'Generates static HTML documentation files'
+  generator_args = [:version_name, :input_files, :output_folder]
+  task :generate, generator_args => :environment  do |_task, args|
+    version, input, output = sanitize_generator_input(args)
+    fail('A version name has to be provided') unless version
+    fail('At leas one input file has to be provided') unless input
+
+    doc = RocketDocs.documentation_for_files(input, version)
+
+    template_folder = generator_template_folder
+    layout_path = template_folder + '/layouts/rocket_docs/application.slim'
+    template_path = template_folder + '/docs/rocket_docs/show.slim'
+
+    prepare_generator_output(output, version, 'html')
+
+    view_builder = generator_view_builder(template_folder)
+    view_builder.instance_variable_set(:@doc, doc)
+    layout = Slim::Template.new { File.open(layout_path, 'r').read }
+    view = Slim::Template.new { File.open(template_path, 'r').read }
+    html = layout.render(view_builder) do
+      view.render(view_builder).html_safe
+    end
+    File.open(output, 'w+') do |file|
+      file.puts(html)
+    end
+  end
+  task :gen, generator_args => :generate
+
+  desc 'Generates static MARKDOWN documentation files'
+  md_generator_args = generator_args
+  task :generate_markdown, md_generator_args => :environment  do |_task, args|
+    version, input, output = sanitize_generator_input(args)
+
+    doc = RocketDocs.documentation_for_files(input, version)
+
+    template_folder = generator_template_folder
+    template_path = template_folder + '/docs/rocket_docs/show.markdown.erb'
+
+    prepare_generator_output(output, version, 'markdown')
+
+    view_builder = generator_view_builder(template_folder)
+    view_builder.instance_variable_set(:@doc, doc)
+    view = ERB.new(File.open(template_path, 'r').read)
+    html = view.result(view_builder.instance_eval { binding })
+    File.open(output, 'w+') do |file|
+      file.puts(html)
+    end
+  end
+  task :generate_md, md_generator_args => :generate_markdown
+  task :gen_md, md_generator_args => :generate_markdown
+
+  ###############
+  ### HELPERS ###
+  ###############
+
+  def sanitize_generator_input(args)
+    version = args[:version_name].presence
+    # TODO: Potential bug with pathnames containing spaces
+    input = args[:input_files] && args[:input_files].split.presence
+    output = args[:output_folder].presence ||
+             Rails.root.join('public', 'system', 'documentation').to_s
+    fail('A version name has to be provided') unless version
+    fail('At leas one input file has to be provided') unless input
+    [version, input, output]
+  end
+
+  def generator_template_folder
+    File.expand_path('../../../app/views', __FILE__)
+  end
+
+  def prepare_generator_output(output, name, ext)
+    FileUtils.mkdir_p(output)
+    output = output[-1] == '/' ? output : output << '/'
+    output << "#{name}.#{ext}"
+  end
+
+  def generator_view_builder(template_folder)
+    lookup_context = ActionView::LookupContext.new(template_folder)
+    view_builder = ActionView::Base.new(lookup_context)
+    view_builder.extend ActionView::Helpers
+    view_builder.extend RocketDocs::ApplicationHelper
+    view_builder
+  end
+end

metadata

@@ -0,0 +1,284 @@
+--- !ruby/object:Gem::Specification
+name: rocket_docs
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Stanko Krtalić Rusendić
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-03-17 00:00:00.000000000 Z
+dependencies:
+- !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: slim-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: jquery-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: sass-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: bootstrap-sass
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: indentation-parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: factory_girl_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+- !ruby/object:Gem::Dependency
+  name: rocket_pants
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: pry-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: better_errors
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: binding_of_caller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Unintrusive interactive API documentation generator for rails apps
+email:
+- stanko.krtalic@gmial.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- Rakefile
+- app/assets/javascripts/rocket_docs/application.js
+- app/assets/stylesheets/rocket_docs/application.scss
+- app/controllers/rocket_docs/application_controller.rb
+- app/helpers/rocket_docs/application_helper.rb
+- app/views/docs/rocket_docs/_action.markdown.erb
+- app/views/docs/rocket_docs/_action.slim
+- app/views/docs/rocket_docs/_controller.markdown.erb
+- app/views/docs/rocket_docs/_controller.slim
+- app/views/docs/rocket_docs/_documentation.markdown.erb
+- app/views/docs/rocket_docs/_documentation.slim
+- app/views/docs/rocket_docs/_hash_param.slim
+- app/views/docs/rocket_docs/_version.slim
+- app/views/docs/rocket_docs/index.slim
+- app/views/docs/rocket_docs/show.markdown.erb
+- app/views/docs/rocket_docs/show.slim
+- app/views/layouts/rocket_docs/_modal.slim
+- app/views/layouts/rocket_docs/_navigation.slim
+- app/views/layouts/rocket_docs/application.slim
+- config/routes.rb
+- lib/rocket_docs.rb
+- lib/rocket_docs/documentation.rb
+- lib/rocket_docs/documentation/action.rb
+- lib/rocket_docs/documentation/controller.rb
+- lib/rocket_docs/engine.rb
+- lib/rocket_docs/parser.rb
+- lib/rocket_docs/router.rb
+- lib/rocket_docs/version.rb
+- lib/tasks/rocket_docs_tasks.rake
+homepage: http://github.com/stankec/Rocket_Docs
+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.4.5
+signing_key: 
+specification_version: 4
+summary: Interactive API documentation for rails apps
+test_files: []