documentation 0.0.1 → 1.0.0

data/app/views/documentation/pages/_admin_buttons.html.haml

@@ -0,0 +1,18 @@
+- canAdd = authorizer.can_add_page?(@page)
+- canEdit = authorizer.can_edit_page?(@page)
+- canReposition = authorizer.can_reposition_page?(@page)
+- canDelete = authorizer.can_delete_page?(@page)
+
+- if canAdd || canEdit || canReposition || canDelete
+  %p.adminButtons
+    - if canAdd
+      = link_to t('.new'), new_page_path(@page.full_permalink), :class => 'button new'
+
+    - if canEdit
+      = link_to t('.edit'), edit_page_path(@page.full_permalink), :class => 'button edit'
+
+    - if canReposition
+      = link_to t('.reorder'), page_positioning_path(@page.parents[-1].try(:full_permalink)), :class => 'button edit'
+
+    - if canDelete
+      = link_to t('.delete'), delete_page_path(@page.full_permalink), :class => 'button delete', :method => :delete, :data => {:confirm => "Are you sure you wish to remove this page?"}

data/app/views/documentation/pages/form.html.haml

@@ -0,0 +1,12 @@
+- @page_title = @page.breadcrumb.reverse.map(&:title).join(" - ")
+
+%section.content
+  = documentation_breadcrumb_for @page
+  = form_for @page, :url => @page.new_record? ? new_page_path(@page.parent ? @page.parent.full_permalink : nil) : edit_page_path(@page.full_permalink), :html => {:class => 'pageForm'} do |f|
+    = error_messages_for @page
+    %p.title= f.text_field :title, :placeholder => t('.title_placeholder')
+    %p.content= f.text_area :content, :placeholder => t('.content_placeholder')
+    %dl
+      %dt= f.label :permalink
+      %dd= f.text_field :permalink, :placeholder => t('.permalink_placeholder')
+    %p.submit= f.submit t('.save'), :class => 'button'

data/app/views/documentation/pages/index.html.haml

@@ -0,0 +1,13 @@
+%section.welcome
+  %h1= t('.welcome_title')
+  %h2= t('.welcome_text')
+
+  - if Documentation.config.developer_tips
+    .override
+      %p= t('.developer_tip').html_safe
+      
+  %p.new
+    - if authorizer.can_add_page?(nil)
+      = link_to t('.create_root_page'), new_page_path, :class => 'button new'
+    - if authorizer.can_reposition_page?(nil)
+      = link_to t('.reorder_root_pages'), page_positioning_path, :class => 'button'

data/app/views/documentation/pages/positioning.html.haml

@@ -0,0 +1,22 @@
+- if @page
+  - @page_title = @page.breadcrumb.reverse.map(&:title).join(" - ")
+  = documentation_breadcrumb_for @page
+- else
+  - @page_title = t('.reorder_root_pages_title')
+  = documentation_breadcrumb_for nil
+
+%section.page
+  %h1= @page ? @page.title : t('.reorder_root_pages_title')
+
+  = form_tag page_positioning_path(@page.try(:full_permalink)), :class => 'reordering' do 
+    %ul
+      - for child in @pages
+        %li
+          = child.title
+          = hidden_field_tag 'order[]', child.id
+  
+  %p.adminButtons
+    - if @page
+      = link_to t('.back_to_page'), page_path(@page.full_permalink), :class => 'button edit'
+    - else
+      = link_to t('.back_to_homepage'), root_path, :class => 'button edit'

data/app/views/documentation/pages/search.html.haml

@@ -0,0 +1,26 @@
+- @page_title = t('.title', :query => params[:query])
+
+%section.page
+  
+  - if @result.empty?
+    %p.noSearchResults= t('.no_results', :query => params[:query])
+  - else
+    %h1= t('.title', :query => params[:query])
+    %p.searchSummary= t('.summary', :total_results => @result.total_results, :start_result => @result.start_result_number, :end_result => @result.end_result_number)
+    
+    %ul.searchResults
+      - for page in @result.results
+        %li
+          %h4= link_to page.title, page_path(page.full_permalink)
+          - unless page.parents.empty?
+            %p.in
+              = t('.in')
+              = page.parents.map { |c| link_to(h(c.title), page_path(c.full_permalink))}.join(" ⇒ ").html_safe
+          %p.excerpt= @result.excerpt_for(page)
+        
+  
+    %p.pagination
+      - unless @result.first_page?
+        = link_to t('.previous_page'), search_path(:query => params[:query], :page => @result.page - 1), :class => 'button'
+      - unless @result.last_page?
+        = link_to t('.next_page'), search_path(:query => params[:query], :page => @result.page + 1), :class => 'button'

data/app/views/documentation/pages/show.html.haml

@@ -0,0 +1,14 @@
+- @page_title = @page.breadcrumb.reverse.map(&:title).join(" - ")
+
+= documentation_breadcrumb_for @page
+
+%section.page
+  - if @page.preview_path
+    %p.previewLink= link_to t('.view_in_website'), @page.preview_path, :class => 'button preview'
+
+  %h1= @page.title
+  %p.updated= t('.last_updated', :timestamp => @page.updated_at.to_s(:long))
+  .documentationMarkdown
+    ~ preserve(documentation_content_for(@page))
+
+  = render 'admin_buttons'

data/app/views/documentation/shared/access_denied.html.haml

@@ -0,0 +1,10 @@
+!!!
+%html.errorPage
+  %head
+    %title= @page_title
+    = stylesheet_link_tag 'documentation/application'
+    = csrf_meta_tags
+  %body
+    %section.errorMessage
+      %h2 Access Denied
+      %p You are not permitted to view this page. If you believe you have received this message in error, please contact the site admin.

data/app/views/documentation/shared/not_found.html.haml

@@ -0,0 +1,10 @@
+!!!
+%html.errorPage
+  %head
+    %title= @page_title
+    = stylesheet_link_tag 'documentation/application'
+    = csrf_meta_tags
+  %body
+    %section.errorMessage
+      %h2 Page Not Found
+      %p No page was found at the path you have entered. Please ensure you have entered the correct URL otherwise contact the site admin.

data/app/views/layouts/documentation/_header.html.haml

@@ -0,0 +1,3 @@
+%header
+  %h1= link_to t('.title'), root_path
+  %p.back= link_to "← #{t('.back_to_site')}".html_safe, "/", :class => ''

data/app/views/layouts/documentation/_search.html.haml

@@ -0,0 +1,5 @@
+- if authorizer.can_search?
+  = form_tag search_path, :method => :get do
+    %p.searchForm
+      = text_field_tag 'query', params[:query], :placeholder => t('.query_placeholder')
+    

data/app/views/layouts/documentation/application.html.haml

@@ -0,0 +1,18 @@
+!!!
+%html
+  %head
+    %title #{@page_title} - #{t('.title')}
+    = stylesheet_link_tag 'documentation/application'
+    = javascript_include_tag 'documentation/application'
+    = csrf_meta_tags
+  %body
+    = render 'layouts/documentation/header'
+    %nav.pages
+      .inner
+        = render 'layouts/documentation/search'
+        = documentation_navigation_tree_for(@page)
+    %section.content
+      .inner  
+        = flash_messages
+        = yield
+        

data/config/locales/en.yml

@@ -0,0 +1,56 @@
+en:
+  layouts:
+    documentation:
+      application:
+        title: Documentation
+      header:
+        title: Documentation
+        back_to_site: Back to site
+      search:
+        query_placeholder: Search Documentation...
+        
+  documentation:
+    
+    helpers:
+      documentation_breadcrumb_for:
+        default_root_link: Home
+    
+    pages:
+      index:
+        welcome_title: Welcome to Documentation
+        welcome_text: Choose a page from the menu on the left of the screen to begin.
+        developer_tip:
+          You can override this page by adding a new view in <code>app/views/documentation/pages/index</code>.
+          Alternatively, you can disable this message by setting <code>developer_tips</code> to false in the
+          Documentation configuration.
+        create_root_page: Create new root page
+        reorder_root_pages: Re-order root pages
+      
+      show:
+        view_in_website: View in website
+        last_updated: Last updated on %{timestamp}
+      
+      admin_buttons:
+        new: New page
+        edit: Edit page
+        reorder: Re-order children
+        delete: Delete page
+      
+      form:
+        title_placeholder: Enter a title for this page
+        content_placeholder: 'Use Markdown to enter page content'
+        permalink_placeholder: Automatically generated if left blank
+        save: Save Page
+      
+      positioning:
+        reorder_root_pages_title: Re-order root pages
+        back_to_page: Back to page
+        back_to_homepage: Back to homepage
+        
+      search:
+        title: "Search results for '%{query}'"
+        no_results: "No pages were found matching '%{query}'"
+        summary: "Found %{total_results} pages matching your query. Showing results %{start_result} to %{end_result}"
+        in: in
+        next_page: Next page
+        previous_page: Previous page

data/config/routes.rb

@@ -0,0 +1,10 @@
+Documentation::Engine.routes.draw do
+  
+  match 'new(/*path)', :to => 'pages#new', :as => 'new_page', :via => [:get, :post]
+  match 'positioning(/*path)', :to => 'pages#positioning', :as => 'page_positioning', :via => [:get, :post]
+  match 'edit(/*path)', :to => 'pages#edit', :as => 'edit_page', :via => [:get, :patch]
+  match 'delete(/*path)', :to => 'pages#destroy', :as => 'delete_page', :via => [:delete]
+  get 'search', :to => 'pages#search', :as => 'search'
+  get '*path' => 'pages#show', :as => 'page'
+  root :to => 'pages#index'
+end

data/db/migrate/20140711185212_create_documentation_pages.rb

@@ -0,0 +1,10 @@
+class CreateDocumentationPages < ActiveRecord::Migration
+  def up
+    create_table "documentation_pages" do |t|
+      t.string :title, :permalink
+      t.text :content, :compiled_content
+      t.integer :parent_id, :position
+      t.timestamps
+    end
+  end
+end

data/db/seeds.rb

@@ -0,0 +1,15 @@
+$doc_root = File.join(File.expand_path(File.join('..', '..'), __FILE__), 'doc')
+
+def doc(*path)
+  File.read(File.join($doc_root, *path))
+end
+
+guide = Documentation::Page.create(:title => "Developers' Guide", :content => doc('developers-guide', 'overview.md'))
+guide.children.create(:title => 'Authorization', :content => doc('developers-guide', 'authorization.md'))
+guide.children.create(:title => 'Search Backends', :content => doc('developers-guide', 'search-backends.md'))
+guide.children.create(:title => 'Customization', :content => doc('developers-guide', 'customization.md'))
+views = guide.children.create(:title => 'Building your own views', :content => doc('developers-guide', 'building-views', 'overview.md'))
+views.children.create(:title => 'Accessing Pages', :content => doc('developers-guide', 'building-views', 'accessing-pages.md'))
+views.children.create(:title => 'Helpers', :content => doc('developers-guide', 'building-views', 'helpers.md'))
+
+markdown = Documentation::Page.create(:title => "Using Markdown", :content => doc('markdown', 'overview.md'))

data/lib/documentation.rb

@@ -1,2 +1,18 @@
+require 'haml'
+require 'coffee-rails'
+require 'sass-rails'
+require 'jquery-rails'
+require 'dynamic_form'
+require 'ostruct'
+
+require 'documentation/version'
+require 'documentation/errors'
+require 'documentation/engine'
+require 'documentation/markdown_renderer'
+require 'documentation/view_helpers'
+require 'documentation/searchers/abstract'
+require 'documentation/search_result'
+require 'documentation/config'
+
 module Documentation
 end

data/lib/documentation/authorizer.rb

@@ -0,0 +1,52 @@
+module Documentation
+  class Authorizer
+    
+    def initialize(controller)
+      @controller = controller
+    end
+    
+    def can_view_page?(page)
+      true
+    end
+
+    def can_add_page?(page)
+      true
+    end
+
+    def can_reposition_page?(page)
+      true
+    end
+
+    def can_delete_page?(page)
+      true
+    end
+
+    def can_edit_page?(page)
+      true
+    end
+    
+    def can_search?
+      true
+    end
+    
+    def check!(action, object = :none)
+      action_method_name = "can_#{action}?"
+      if self.respond_to?(action_method_name)
+        result = object == :none ? self.send(action_method_name) : self.send(action_method_name, object)
+        if result != true
+          raise Documentation::AccessDeniedError, "You are not permitted to perform this action."
+        end
+      else
+        raise Documentation::Error, "Invalid authorizer check (#{action})"
+      end
+    end
+    
+    private
+    
+    def request
+      controller.request
+    end
+    
+    
+  end
+end

data/lib/documentation/config.rb

@@ -0,0 +1,31 @@
+require 'documentation/authorizer'
+require 'documentation/searchers/simple'
+
+module Documentation
+  
+  #
+  # Sets the default configuration
+  #
+  DEFAULT_CONFIGURATION = {
+    # This defines the at path where a page can be viewed in
+    # the source website. For example, /docs/
+    :preview_path_prefix => nil,
+
+    # Should we display developer tips in the UI?
+    :developer_tips => true,
+
+    # The authorizer to use
+    :authorizer => Documentation::Authorizer,
+    
+    # The searcher to use
+    :searcher => Documentation::Searchers::Simple.new
+  }
+  
+  #
+  # Return configuration options
+  #
+  def self.config
+    @config ||= OpenStruct.new(DEFAULT_CONFIGURATION)
+  end
+  
+end

data/lib/documentation/engine.rb

@@ -0,0 +1,29 @@
+module Documentation
+  class Engine < Rails::Engine
+    
+    isolate_namespace Documentation
+    
+    initializer 'shoppe.initialize' do |app|
+      
+      config.paths["db/migrate"].expanded.each do |expanded_path|
+        app.config.paths["db/migrate"] << expanded_path
+      end
+      
+      # Load view helpers for the base application
+      ActiveSupport.on_load(:action_view) do
+        ActionView::Base.send :include, Documentation::ViewHelpers
+      end
+    end
+    
+    generators do
+      require 'documentation/generators/setup_generator'
+    end
+    
+    def self.mounted_path
+      if route = Rails.application.routes.routes.select { |r| r.app == self }.first
+        route.path.spec.to_s
+      end
+    end
+    
+  end
+end

data/lib/documentation/errors.rb

@@ -0,0 +1,7 @@
+module Documentation
+  class Error < StandardError
+  end
+  
+  class AccessDeniedError < Error
+  end
+end

data/lib/documentation/generators/setup_generator.rb

@@ -0,0 +1,13 @@
+require 'rails/generators'
+
+module Documentation
+  module Generators
+    class SetupGenerator < Rails::Generators::Base
+      
+      def create_route
+        route 'mount Documentation::Engine => "/docs"'
+      end
+
+    end
+  end
+end

data/lib/documentation/markdown_renderer.rb

@@ -0,0 +1,62 @@
+require 'redcarpet'
+require 'pygments'
+
+module Documentation
+  class MarkdownRenderer < Redcarpet::Render::HTML
+    
+    attr_accessor :page
+  
+    include ActionView::Helpers::TagHelper
+    
+    def block_code(code, language)
+      title = nil
+      code.gsub!(/\A\:\:(.*)$/) { title = $1 ; nil }
+      String.new.tap do |s|
+        s << "<p class='codeTitle'>#{title}</p>" if title
+        s << Pygments.highlight(code, :lexer => language)
+      end
+    rescue 
+      "<div class='highlight'><pre>#{code}</pre></div>"
+    end
+    
+    def link(link, title, content)
+      if link =~ /\A\^/
+        case link
+        when /\A\^\.\/(.*)/
+          # ^./pagename
+          # Links to pages on the same level as the current page
+          link = "{{docRoot}}/#{page.parents.map(&:permalink).join('/')}/#{$1}"
+        when /\A\^\/(.*)/
+          # ^/full/path
+          # Links to a page frmo the root of the docs
+          link = "{{docRoot}}/#{$1}"
+        when /\A\^(.*)/
+          # ^child/item
+          # Links to a child of the current page
+          link = "{{docRoot}}/#{page.full_permalink}/#{$1}"
+        end
+      end
+      "<a href='#{link}' title='#{title}'>#{content}</a>"
+    end
+  
+    def image(src, title, alt)
+      if alt.gsub!(/\*([\w\-\s]+)\z/, '')
+        klass = "imgcontainer #{$1}"
+      else
+        klass = nil
+      end
+      content_tag :span, tag(:img, :src => src, :title => title, :alt => alt), :class => klass
+    end
+  
+    def paragraph(text)
+      klass = ''
+      text.gsub!(/\A(\w+)\:/) do
+        klass = $1
+        nil
+      end
+      text.sub!(/ ([^ ]+)$/, '&nbsp;\1')
+      "<p class='#{klass.downcase}'>#{text}</p>"
+    end
+  
+  end
+end