local_documentation 1.0.0

data/doc/developers-guide/building-views/overview.md

@@ -0,0 +1,3 @@
+In many cases, it may be easier to build your own views and use the built-in interface for admin actions.  The library provides a number of helpers and useful model methods allowing you to easily access content and render it without much effort at all.
+
+{{nav}}

data/doc/developers-guide/customization.md

@@ -0,0 +1,9 @@
+As with all Rails engines, you can customize every aspect of the engine within your Rails application.
+
+## Overriding views
+
+You can override views by simply placing new view files in your `app/views` folder. You can see the files which exist and can be overridden in [our views directory](https://github.com/qbraksa/documentation/tree/master/app/views). We use Haml for our views but you can use whatever you want when overriding.
+
+## Internationalization
+
+The interface pulls all its wording from the Rails i18n system. This means you can simply override any wording in your own locale files. The keys available can be found in [our en.yml file](https://github.com/qbraksa/documentation/blob/master/config/locales/en.yml).

data/doc/developers-guide/overview.md

@@ -0,0 +1,20 @@
+**Welcome to Documentation.** You can go ahead and delete this page whenever you're ready. It contains some information as well as being a good reference point for how things will be styled. Every page in Documentation is formatted with Markdown (although there are a couple of additions which are demonstrated here).
+
+## Features
+
+* A simple & attractive interface for viewing & editing your pages
+* Store pages in a hierarchy
+* Modular authorisation architecture
+* Modular search backend architecture
+* Full i18n support
+* Override any views as necessary within your Rails application
+
+Recommendation: Take a look through all the pages in this guide while developing your application. If you delete this section, you can always re-add it by running `rake documentation:install_guides` from the root of your Rails application.
+
+## Useful links
+
+The links below provide you with easy access to key resources which will help you.
+
+* [Browse source code on GitHub](https://github.com/qbraksa/documentation)
+* [View issues](https://github.com/qbraksa/documentation/issues)
+* [Check out the installation guide](https://github.com/qbraksa/documentation/blob/master/README.md)

data/doc/developers-guide/search-backends.md

@@ -0,0 +1,17 @@
+By default, Documentation uses a very very simple search which uses a LIKE query on your database. As this method is far from ideal, Documentation allows additional search backends to be created. 
+
+## Elasticsearch
+
+The recommended method of indexing & searching data is to use Elasticsearch. A module is provided for this [on GitHub](https://github.com/adamcooke/documentation-elasticsearch) and can be installed by following the instructions on the repo's README page.
+
+## Creating your own search backend
+
+To create your own backend, create a new class which inherits from `Documentation::Searchers::Abstract`. This class must confirm to the protocol outlined in this [abstract.rb](https://github.com/qbraksa/documentation/blob/master/lib/documentation/searchers/abstract.rb) file.
+
+## Using your custom backend
+
+Once you have created a backend, you should tell Documentation to use it. Just add the following to your `config/initializers/documentation.rb` file.
+
+```ruby
+Documentation.config.searcher = MyCustomSearcher.new
+```

data/doc/markdown/overview.md

@@ -0,0 +1,37 @@
+Pages all use standard Markdown markup to format them. There are some additional options though which you may find useful:
+
+## Linking to other pages
+
+If you need to link to other documentation pages, it is important to use the following syntax to ensure the link is maintain regardless of how the page is rendered.
+
+* `[Page](^permalink)` - links from a child of the page where the link is shown
+* `[Page](^./permalink)` - links from a sibling of the page where the link is shown
+* `[Page](^/permalink) `- links from the root page
+
+It is important to ensure the `^` character is maintained.
+
+## Code Highlighting
+
+Code highlighting is handled by [Pygments](http://pygments.org/). This is a Python library and you may need to install it. Fortunately, installing it is usually as simple as running:
+
+```text
+easy_install pygments
+```
+
+## Recommendations & Warnings
+
+Any paragraph which is prefixed with `Recommendation:` or `Warning:` will be styled as appropriate. Recommendations are displayed with an information icon and a blue background and warnings are displayed with a warning icon and a yellow background. As shown below:
+
+Recommendation: This is an example recommendation
+
+Warning: This is an example warning.
+
+## Images
+
+If you are embedding images, it is usually best to embed them in the centre of the page. To do to this, simply use the following Markdown:
+
+```text
+![My image*center](path/to/image.png)
+```
+
+This will embed the image in a `imgcontainer` element with the `center` class. The stylesheet will then take care of the rest.

data/lib/documentation.rb

@@ -0,0 +1,20 @@
+require 'haml'
+require 'coffee-rails'
+require 'sass-rails'
+require 'jquery-rails'
+require 'dynamic_form'
+require 'ostruct'
+require 'nifty/attachments'
+require 'nifty/dialog'
+
+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,60 @@
+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_upload?(page)
+      true
+    end
+    
+    def can_search?
+      true
+    end
+    
+    def can_use_ui?
+      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,17 @@
+require 'rails/generators'
+
+module Documentation
+  module Generators
+    class SetupGenerator < Rails::Generators::Base
+      
+      def create_route
+        route 'mount Documentation::Engine => "/docs"'
+      end
+
+      def migrate_database
+      	rake("documentation:db:migrate")
+      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

data/lib/documentation/search_result.rb

@@ -0,0 +1,84 @@
+module Documentation
+  class SearchResult
+    
+    attr_accessor :query
+    attr_accessor :time
+    attr_accessor :raw_results
+    attr_accessor :results
+    attr_accessor :page
+    attr_accessor :per_page
+    attr_accessor :total_results
+    
+    def initialize
+      @time = nil
+      @raw_results = {}
+      @page = 1
+      @total_pages = 1
+      @per_page = nil
+    end
+    
+    #
+    # Return the pages
+    #
+    def results
+      @results ||= begin
+        results = Documentation::Page.where(:id => raw_results.keys).includes(:parent).to_a
+        results.sort_by { |p| raw_results.keys.index(p.id) }
+      end
+    end
+    
+    #
+    # Return the highlight string for a given page
+    #
+    def excerpt_for(page)
+      if @raw_results[page.id] && hl = @raw_results[page.id][:highlights]
+        ERB::Util.html_escape((hl.join("..."))).gsub('{{{', "<mark>").gsub("}}}", "</mark>").html_safe
+      else
+        page.content[0,255].gsub(/[\n\r]/, '') + "..."
+      end
+    end
+    
+    #
+    # Is the result set empty?
+    #
+    def empty?
+      self.results.empty?
+    end
+    
+    #
+    # The total number of pages in the result set
+    #
+    def total_pages
+      (total_results / per_page.to_f).ceil
+    end
+    
+    #
+    # The number of the first result on the current page
+    #
+    def start_result_number
+      ((page - 1) * per_page) + 1
+    end
+    
+    #
+    # The number of the last result on the current page
+    #
+    def end_result_number
+      start_result_number + (results.size) - 1
+    end
+    
+    #
+    # Is this the first page of the result set?
+    #
+    def first_page?
+      page == 1
+    end
+    
+    #
+    # Is this the last page of the result set?
+    #
+    def last_page?
+      page == total_pages
+    end
+    
+  end
+end

data/lib/documentation/searchers/abstract.rb

@@ -0,0 +1,47 @@
+module Documentation
+  module Searchers
+    class Abstract
+      
+      attr_reader :options
+      
+      def initialize(options = {})
+        @options = options
+        setup
+      end
+      
+      #
+      # Run whatever initial set up is needed
+      #
+      def setup
+      end
+      
+      #
+      # Search for a page from the index
+      #
+      def search(query, options = {})
+        []
+      end
+      
+      #
+      # Delete a page from the index
+      #
+      def delete(page)
+        false
+      end
+      
+      #
+      # Reset an index to have no data within it
+      #
+      def reset
+        true
+      end
+      
+      #
+      # Add or update an page in the index
+      #
+      def index(page)
+      end
+      
+    end
+  end
+end