api_docs_engine 0.1.0

data/app/models/docs/page_category.rb

@@ -0,0 +1,30 @@
+module Docs
+  class PageCategory < ActiveRecord::Base
+    extend FriendlyId
+    friendly_id :slug, use: :slugged
+    has_many :pages
+    alias_attribute :name, :title
+    
+    before_validation :set_missing_title, unless: :title?
+    
+    validates :slug, :title, presence: true
+    validates :slug, uniqueness: true, on: :create
+    
+    def weight
+      @weight ||= splitted_title[0].to_i.nonzero? || 100
+    end
+    
+    def only_title
+      @captures ||= splitted_title[1]
+    end
+    
+    def splitted_title
+      @splitted_title ||= title.match(/^(?:(\d+)\. )?(.+)$/).captures
+    end
+    
+    private
+    def set_missing_title
+      self.title = slug.to_s.titleize
+    end
+  end
+end

data/app/models/docs/routes_collection.rb

@@ -0,0 +1,71 @@
+module Docs
+  class RoutesCollection
+    include Enumerable
+    attr_reader :routes
+    
+    def initialize(filter = nil)
+      filter ||= Docs.missing_routes_filter
+      @routes = Inspector.new(Rails.application.routes.routes).enumerate(filter)
+    end
+    
+    def [](name)
+      routes[name]
+    end
+    
+    def each(&block)
+      routes.each(&block)
+      self
+    end
+    
+    def by_controller
+      routes.group_by(&:controller)
+    end
+    
+    class Item
+      attr_accessor :path, :via, :reqs, :pattern, :controller, :action
+      
+      def initialize(route)
+        @path    = route.path.sub(/\(\.:format\)$/, '.json')
+        @via     = route.verb
+        @reqs    = route.reqs
+        @pattern = route.json_regexp
+        @controller, @action = reqs.split("#")
+      end
+      
+      def to_page_attributes
+        { path: path, via: via, reqs: reqs, page_category_slug: controller[/^api\/(\w+)/, 1] }
+      end
+      
+      def inspect
+        "#{via} #{path} => #{reqs}"
+      end
+    end
+    
+    class Inspector < ::ActionDispatch::Routing::RoutesInspector    
+      def enumerate(filter = nil)
+        routes_to_display = filter_routes(filter)
+        collect_routes(routes_to_display)
+      end
+    
+      private
+      def filter_routes(filter)
+        if filter
+          @routes.select { |route| route.defaults[:controller] =~ filter }
+        else
+          @routes
+        end
+      end
+    
+      def collect_routes(routes)
+        routes.collect do |route|
+          ActionDispatch::Routing::RouteWrapper.new(route)
+        end.reject do |route|
+          route.internal?
+        end.collect do |route|
+          collect_engine_routes(route)
+          Item.new(route)
+        end
+      end
+    end
+  end
+end

data/app/views/docs/application/edit.html.slim

@@ -0,0 +1,2 @@
+- content_for :title, "Edit #{controller_name.singularize.humanize} ##{resource.try(:id)}"
+= render "form"

data/app/views/docs/application/new.html.slim

@@ -0,0 +1,2 @@
+- content_for :title, "New #{controller_name.singularize.humanize}"
+= render "form"

data/app/views/docs/layouts/docs.html.slim

@@ -0,0 +1,24 @@
+doctype 5
+html lang="en"
+  head
+    meta charset="utf-8"
+    meta name="viewport" content="width=device-width, initial-scale=1.0"
+    title = content_for?(:title) ? yield(:title) : Docs.title
+    = csrf_meta_tags
+    = stylesheet_link_tag "docs", media: "all"
+    = javascript_include_tag "docs"
+  body
+    .container-fluid
+      .row
+        #left-sidebar.col-sm-3.col-md-2.sidebar
+          ul.nav.nav-sidebar
+            - Docs::PageCategory.all.sort_by(&:weight).each do |c|
+              = li_active_to c.only_title, page_category_pages_path(c), data: { edit_path: edit_page_category_path(c) }
+          .row
+            .btn-group.btn-group-xs.pull-right
+              = link_to fa_icon(:plus, text: "Add category"), new_page_category_path, class: "btn btn-default"
+              = link_to fa_icon(:warning, text: "Missing"),   missing_docs_path,      class: "btn btn-default"
+        
+        .col-sm-9.col-sm-offset-3.col-md-10.col-md-offset-2.main
+          h1.page-header = content_for?(:title) ? yield(:title) : Docs.title
+          = yield

data/app/views/docs/markdown/create.json.erb

@@ -0,0 +1,3 @@
+{ 
+  "result": "<%=j markdown(params[:source]) %>"
+}

data/app/views/docs/missing_docs/index.html.slim

@@ -0,0 +1,9 @@
+- content_for :title, "Missing"
+table.table
+  tbody
+    - @missing_docs.each do |route|
+      tr
+        td = route.path
+        td = route.via
+        td = route.reqs
+        td = link_to "Create page", new_page_path(page: route.to_page_attributes), class: "btn btn-default btn-sm"

data/app/views/docs/page_categories/_form.html.slim

@@ -0,0 +1,19 @@
+= semantic_form_for @page_category do |f|
+  .row
+    .col-sm-5
+      = f.input :title
+    .col-sm-5
+      = f.input :slug
+    .col-sm-2 style="padding-top: 25px;"
+      = f.action :submit, button_html: { class: "btn btn-primary btn-block" }
+  
+  ul.nav.nav-tabs role="tablist"
+    li.active = link_to "Description", "#desc",    role: 'tab', data: { toggle: 'tab' }
+    li        = link_to "Preview",     "#preview", role: 'tab', data: { toggle: 'tab' }
+  
+  = f.inputs do
+    .tab-content
+      #desc.tab-pane.fade.in.active
+        = f.input :body, input_html: { rows: 30, class: "process-markdown" }, label: false
+      #preview.tab-pane
+        .preview-markdown data-source=".process-markdown"

data/app/views/docs/pages/_form.html.slim

@@ -0,0 +1,35 @@
+= semantic_form_for @page do |f|
+  .row
+    .col-sm-6
+      = f.input :title
+    .col-sm-4
+      = f.input :page_category_slug
+    .col-sm-2 style="padding-top: 25px;"
+      = f.action :submit, button_html: { class: "btn btn-primary btn-block" }
+  .row
+    .col-sm-2
+      = f.input :via
+    .col-sm-4
+      = f.input :path
+    .col-sm-4
+      = f.input :reqs
+    .col-sm-2
+      = f.input :weight
+  
+  ul.nav.nav-tabs role="tablist"
+    li.active
+      = link_to "Description", "#desc", role: 'tab', data: { toggle: 'tab' }
+    li
+      = link_to fa_icon(:eye, text: "Preview"), "#preview", role: 'tab', data: { toggle: 'tab' }
+    li
+      = link_to fa_icon(:code, text: "Example"), "#example", role: 'tab', data: { toggle: 'tab' }
+  
+  
+  = f.inputs do
+    .tab-content
+      #desc.tab-pane.fade.in.active
+        = f.input :body, input_html: { rows: 30, class: "process-markdown" }, label: false
+      #preview.tab-pane
+        .preview-markdown data-source=".process-markdown"
+      #example.tab-pane 
+        = f.input :example, input_html: { rows: 20 }, label: false

data/app/views/docs/pages/_page.html.slim

@@ -0,0 +1,24 @@
+.action
+  h3 id=page.anchor = page.title
+
+  .panel.panel-default
+    .panel-heading
+      code == "#{content_tag :strong, page.via} #{page.only_path}#{content_tag :span, page.only_query, class: 'text-muted'}"
+    .navbar.navbar-default.navbar-static-top.panel-navbar
+      ul.nav.navbar-nav role="tablist"
+        li class=( "active" if page.body.present? )
+          = link_to fa_icon('info-circle'), "##{page.anchor}-desc", role: "tab", data: { toggle: "tab" }
+        li class=( "active" unless page.body.present? )
+          = link_to fa_icon(:code, text: "Example"), "##{page.anchor}-example", role: "tab", data: { toggle: "tab" }
+        li
+          = link_to fa_icon(:edit), edit_page_path(page)
+    
+    .tab-content.panel-body
+      .tab-pane id="#{page.anchor}-desc" class=( "active" if page.body.present? )
+        p
+        - if page.body?
+          == markdown(page.body)
+      .tab-pane id="#{page.anchor}-example" class=( "active" unless page.body.present? )
+        p
+        - if page.example?
+          pre: samp.json == page.example

data/app/views/docs/pages/index.html.slim

@@ -0,0 +1,34 @@
+- content_for :title, @page_category.only_title
+
+.row
+  .col-md-9
+    - if @pages.any?
+      .panel.panel-default
+        .panel-heading: h4.panel-title Методы
+        table.table.table-condensed
+          tbody
+            - @pages.each do |page|
+              tr
+                td
+                  code == "#{content_tag :strong, page.via} #{page.only_path}"
+                td 
+                  = link_to page.title, "##{page.anchor}"
+                td 
+                  small.text-muted = page.reqs
+    
+    - if @page_category.body?
+      == markdown(@page_category.body)
+    
+    - if @pages.any? 
+      .actions
+        = render @pages
+  
+  .col-md-3
+    .navbar-spyscroll
+      ul.nav.nav-right-spy role="tablist"
+        - @pages.each do |page|
+          li = link_to "#{content_tag(:strong, page.via)} #{page.only_path}".html_safe, "##{page.anchor}"
+      hr /
+      .btn-group.btn-group-xs
+        = link_to fa_icon(:edit, text: "Edit"),     [:edit, @page_category],       class: "btn btn-default"
+        = link_to fa_icon(:plus, text: "Add page"), [:new, @page_category, :page], class: "btn btn-default"

data/config/initializers/formtastic.rb

@@ -0,0 +1 @@
+Formtastic::Helpers::FormHelper.builder = FormtasticBootstrap::FormBuilder

data/config/routes.rb

@@ -0,0 +1,5 @@
+Docs::Engine.routes.draw do
+  scope "docs" do
+    Docs.route(self)
+  end
+end

data/lib/api_docs_engine/docs.rb

@@ -0,0 +1,50 @@
+require 'slim-rails'
+require 'sass-rails'
+require 'jquery-rails'
+require 'coffee-rails'
+require 'bootstrap-sass'
+require 'font-awesome-rails'
+require 'redcarpet'
+require 'friendly_id'
+require 'formtastic'
+require 'formtastic-bootstrap'
+require 'turbolinks'
+
+module Docs
+  mattr_accessor :title
+  @@title = "API documentation"
+  
+  mattr_accessor :root_path
+  @@root_path = "missing_docs#index"
+  
+  mattr_accessor :missing_routes_filter
+  @@missing_routes_filter = /api\/.*/
+  
+  mattr_accessor :api_docs_prefix
+  @@api_docs_prefix = "api"
+  
+  mattr_accessor :auth
+  @@auth = nil
+  
+  class << self
+    def setup
+      yield self
+    end
+    
+    def route(router)
+      router.instance_exec do
+        root Docs.root_path
+        
+        resources :missing_docs,    only: [:index]    
+        resources :page_categories, except: [:index, :show, :edit]
+        resources :pages,           except: [:index, :show]
+        
+        resources :page_categories, shallow: true, path: Docs.api_docs_prefix, only: [:edit] do
+          resources :pages, only: [:index, :new, :create], path: "", path_names: { new: "new_page" }
+        end
+        
+        resources :markdown, only: "create"
+      end
+    end
+  end
+end

data/lib/api_docs_engine.rb

@@ -0,0 +1,2 @@
+require "api_docs_engine/docs"
+require "docs/engine"

data/lib/bootstrap/active_link_to.rb

@@ -0,0 +1,135 @@
+require "docs/core_ext"
+
+module Bootstrap
+  module ActiveLinkTo
+    class ActiveLink
+      ACTIVE_OPTIONS = [:active, :class_active, :class_inactive, :active_disable]
+    
+      def initialize(context)
+        @context = context
+      end
+    
+      def render(*args, &block)
+        @name           = block_given? ? capture(&block) : args.shift
+        @link_options   = args.extract_options!
+        @url            = h.url_for(args.shift)
+        @active_options = @link_options.extract!(*ACTIVE_OPTIONS).only_presented
+        @after_link     = @link_options.delete(:after_link).to_s
+        
+        if is_wrap?
+          provide_wrap_with_content!
+        else
+          @link_options.smart_append_to :class, active_class
+          content
+        end
+      end
+    
+      private
+      def content
+        "#{link}#{@after_link}".html_safe
+      end
+    
+      def h
+        @context
+      end
+    
+      def link
+        return @name if is_active? && is_active_disable?
+        h.link_to @name, @url, @link_options
+      end
+    
+      def is_active?
+        @is_active = h.is_active_link?(@url, @active_options[:active]) if @is_active.nil?
+        @is_active
+      end
+    
+      def is_wrap?
+        !@link_options[:wrap_tag].nil?
+      end
+    
+      def is_dropdown?
+        !@link_options[:dropdown].nil?
+      end
+    
+      def is_active_disable?
+        !!@active_options[:active_disable]
+      end
+    
+      def provide_wrap_with_content!
+        @link_options[:wrap_options] ||= {}
+        @wrap_options, wrap_tag = @link_options.extract!(:wrap_options, :wrap_tag).values
+        @wrap_options.smart_append_to :class, active_class
+      
+        provide_dropdown! if is_dropdown?
+      
+        h.content_tag wrap_tag, content, @wrap_options
+      end
+    
+      def provide_dropdown!
+        dropdown_html, dropdown = @link_options.extract!(:dropdown_html, :dropdown).values
+        @wrap_options.smart_append_to :class, 'dropdown'
+        @link_options.smart_update class: ['dropdown-toggle'], id: dropdown, data: {toggle: 'dropdown', hover: 'dropdown'}
+        @after_link << dropdown_html.to_s
+      end
+    
+      def active_class
+        h.active_link_to_class(@url, @active_options, is_active?)
+      end
+    end
+  
+    # Wrapper around link_to. Accepts following params:
+    #   :active         => Boolean | Symbol | Regex | Controller/Action Pair
+    #   :class_active   => String
+    #   :class_inactive => String
+    #   :disable_active => Boolean
+    #   :wrap_tag       => Symbol
+    # Example usage:
+    #   active_link_to('/users', :class_active => 'enabled')
+    #   active_link_to(users_path, :active => :exclusive, :wrap_tag => :li)
+    def active_link_to(*args, &block)
+      ActiveLink.new(self).render(*args, &block)
+    end
+  
+    # Returns css class name. Takes the link's URL and its params
+    # Example usage:
+    #   active_link_to_class('/root', :class_active => 'on', :class_inactive => 'off')
+    #
+    def active_link_to_class(url, options={}, is_active=nil)
+      is_active = is_active_link?(url, options[:active]) if is_active.nil?
+      is_active ? (options[:class_active] ||= 'active') : options[:class_inactive]
+    end
+
+    # Returns true or false based on the provided path and condition
+    # Possible condition values are:
+    #                  Boolean -> true | false
+    #                   Symbol -> :exclusive | :inclusive
+    #                    Regex -> /regex/
+    #   Controller/Action Pair -> [[:controller], [:action_a, :action_b]]
+    # Example usage:
+    #   is_active_link?('/root', true)
+    #   is_active_link?('/root', :exclusive)
+    #   is_active_link?('/root', /^\/root/)
+    #   is_active_link?('/root', ['users', ['show', 'edit']])
+    #
+    def is_active_link?(url, condition = nil)
+      url = url_for(url).sub(/\?.*/, '') # ignore GET params
+      case condition
+      when :inclusive, nil
+        !request.fullpath.match(/^#{Regexp.escape(url)}(\/.*|\?.*)?$/).blank?
+      when :exclusive
+        !request.fullpath.match(/^#{Regexp.escape(url)}\/?(\?.*)?$/).blank?
+      when Regexp
+        !request.fullpath.match(condition).blank?
+      when Array
+        controllers = [*condition[0]]
+        actions     = [*condition[1]]
+        (controllers.blank? || controllers.member?(params[:controller])) &&
+        (actions.blank? || actions.member?(params[:action]))
+      when TrueClass
+        true
+      when FalseClass
+        false
+      end
+    end
+  end
+end

data/lib/bootstrap/markdown_renderer.rb

@@ -0,0 +1,10 @@
+module Bootstrap
+  class MarkdownRenderer < Redcarpet::Render::HTML
+    def table(header, body)
+      %{<table class="table table-bordered">
+          #{header}
+          #{body}
+        </table>}
+    end
+  end
+end

data/lib/docs/core_ext.rb

@@ -0,0 +1,39 @@
+class Hash
+  def smart_append_to(key, value, delimeter=' ')
+    if self[key].nil?
+      self[key] ||= value
+    else
+      self[key] << delimeter if self[key].is_a?(String)
+      self[key] << value
+    end
+  end
+  
+  def smart_merge(other)
+    return self unless other.is_a? Hash and other.any?
+    return other unless self.any?
+    
+    self.merge other do |key, left, right| 
+      case left
+        when Hash
+          right.is_a?(Hash) ? left.smart_merge(right) : right
+        when Array
+          (left | [right]).flatten
+        when String
+          right.is_a?(Array) ? ([left]|right).flatten : right
+        else right
+      end
+    end
+  end
+  
+  def smart_merge!(other_hash)
+    self.replace(empty? ? other_hash : smart_merge(other_hash))
+  end
+  
+  def smart_update(other_hash)
+    self.replace(other_hash.smart_merge(self))
+  end
+  
+  def only_presented
+    select {|_, v| v.present? }
+  end
+end

data/lib/docs/engine.rb

@@ -0,0 +1,9 @@
+module Docs
+  class Engine < ::Rails::Engine
+    isolate_namespace Docs
+    
+    initializer "docs.asset_precompile_paths" do |app|
+      app.config.assets.precompile += %w(docs.*)
+    end
+  end
+end

data/lib/generators/active_record/api_docs_engine_generator.rb

@@ -0,0 +1,16 @@
+require 'rails/generators/active_record'
+require 'generators/api_docs_engine/orm_helpers'
+
+module ActiveRecord
+  module Generators
+    class ApiDocsEngine < ActiveRecord::Generators::Base
+      source_root File.expand_path("../templates", __FILE__)
+
+      include ::ApiDocsEngine::Generators::OrmHelpers
+
+      def copy_api_docs_engine_migration
+        migration_template "migration.rb", "db/migrate/api_docs_create.rb"
+      end
+    end
+  end
+end

data/lib/generators/active_record/templates/migration.rb

@@ -0,0 +1,27 @@
+class ApiDocsCreate < ActiveRecord::Migration
+  def up
+    enable_extension :hstore
+
+    create_table :docs_page_categories do |t|
+      t.string :slug, index: { unique: true }
+      t.string :title
+      t.text :body
+    end
+    
+    create_table :docs_pages do |t|
+      t.belongs_to :page_category, index: true
+      t.string :path
+      t.string :via
+      t.string :title
+      t.text :body
+      t.text :example
+      t.hstore :data
+    end
+  end
+  
+  def down
+    drop_table :docs_pages
+    drop_table :docs_page_categories
+    disable_extension :hstore    
+  end
+end

data/lib/generators/api_docs_engine/api_docs_engine_generator.rb

@@ -0,0 +1,12 @@
+require 'rails/generators/base'
+
+module ApiDocsEngine
+  module Generators
+    class ApiDocsEngineGenerator < Rails::Generators::Base
+      hook_for :orm
+      
+      namespace "api_docs_engine"
+      source_root File.expand_path("../templates", __FILE__)
+    end
+  end
+end

data/lib/generators/api_docs_engine/install_generator.rb

@@ -0,0 +1,16 @@
+require 'rails/generators/base'
+require 'securerandom'
+
+module ApiDocsEngine
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../templates", __FILE__)
+      
+      class_option :orm
+      
+      def copy_initializer
+        template "api_docs_engine.rb", "config/initializers/api_docs_engine.rb"
+      end
+    end
+  end
+end

data/lib/generators/api_docs_engine/orm_helpers.rb

@@ -0,0 +1,10 @@
+module ApiDocsEngine
+  module Generators
+    module OrmHelpers
+      private
+      def migration_path
+        @migration_path ||= File.join("db", "migrate")
+      end
+    end
+  end
+end

data/lib/generators/templates/api_docs_engine.rb

@@ -0,0 +1,11 @@
+Docs.setup do |config|
+  # config.title = "API documentation"
+  # config.root_path = { to: "pages#index", defaults: { page_category_id: "common" }}
+  # config.missing_routes_filter = /api\/.*/
+  # config.api_docs_prefix = "api"
+  # config.auth = Proc.new do |controller|
+  #   controller.class_eval do
+  #     http_basic_authenticate_with name: "admin", password: "admin", only: nil
+  #   end
+  # end
+end