local_documentation 1.0.0

data/app/models/documentation/screenshot.rb

@@ -0,0 +1,15 @@
+module Documentation
+  class Screenshot < ActiveRecord::Base
+  	establish_connection :documentation
+
+    attachment :upload
+
+    before_validation do
+      if self.upload_file && self.alt_text.blank?
+        self.alt_text = self.upload_file.original_filename 
+      end
+      true
+    end
+
+  end
+end

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,16 @@
+- @page_title = @page.breadcrumb.reverse.map(&:title).join(" - ")
+
+%section.content.edit-article
+  = 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
+      - if authorizer.can_upload?(@page)
+        = link_to t('.add_screenshot'), upload_screenshot_path, :class => 'button preview js-screenshot'
+      = 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/screenshot.html.haml

@@ -0,0 +1,15 @@
+= form_for @screenshot, :url => upload_screenshot_path, :html => {:class => 'pageForm'} do |f|
+  %dl
+    %dt= f.label :upload_file, "Upload File"
+    %dd.padded
+      - if params[:filename]
+        = params[:filename]
+      - else
+        = f.file_field :upload_file
+
+  %dl
+    %dt= f.label :alt_text, "Screenshot Title"
+    %dd= f.text_field :alt_text
+
+  %p.submit
+    = f.submit "Upload Screenshot", :class => 'button'

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

@@ -0,0 +1,12 @@
+- @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= documentation_search_summary(@result)
+    = documentation_search_results(@result)        
+    %p.pagination= documentation_search_pagination(@result, :link_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,22 @@
+!!!
+%html
+  %head
+    %title #{@page_title} - #{t('.title')}
+    = stylesheet_link_tag 'documentation/application'
+    = javascript_include_tag 'documentation/application'
+    = csrf_meta_tags
+    = render 'layouts/documentation/head'
+    = yield :head
+  %body
+    = render 'layouts/documentation/header'
+    
+    %nav.pages
+      .inner
+        = render 'layouts/documentation/search'
+        = documentation_navigation_tree_for(@page)
+    %section.content
+      .inner  
+        = flash_messages
+        = yield
+        = render 'layouts/documentation/footer'
+    

data/config/locales/en.yml

@@ -0,0 +1,62 @@
+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
+      documentation_search_summary:
+        text: "Found %{total_results} pages matching your query. Showing results %{start_result} to %{end_result}"
+      documentation_search_results:
+        in: in
+      documentation_search_pagination:
+        next: Next page
+        previous: Previous page
+        
+    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
+        add_screenshot: Add Screenshot
+        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}'"
+        next_page: Next page
+        previous_page: Previous page

data/config/routes.rb

@@ -0,0 +1,11 @@
+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]
+  match 'screenshot', :to => 'pages#screenshot', :as => 'upload_screenshot', :via => [:get, :post]
+  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/migrate/20140724111844_create_nifty_attachments_table.rb

@@ -0,0 +1,16 @@
+class CreateNiftyAttachmentsTable < ActiveRecord::Migration
+  
+  def up
+    create_table :nifty_attachments do |t|
+      t.integer :parent_id
+      t.string  :parent_type, :token, :digest, :role, :file_name, :file_type
+      t.binary :data, :limit => 10.megabytes
+      t.timestamps
+    end
+  end
+  
+  def down
+    drop_table :nifty_attachments
+  end
+  
+end

data/db/migrate/20140724114255_create_documentation_screenshots.rb

@@ -0,0 +1,7 @@
+class CreateDocumentationScreenshots < ActiveRecord::Migration
+  def change
+    create_table :documentation_screenshots do |t|
+      t.string :alt_text
+    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/doc/developers-guide/authorization.md

@@ -0,0 +1,37 @@
+By default, all pages you create will be visible & editable by anyone. In order to add a level of authorisation, you can define an **Authorizer** what level of access is given to each request.
+
+## Creating an authorizer class
+
+To do this, begin by creating a new class which inherits from `Documentation::Authorizer`. 
+
+```ruby
+class MyDocsAuthorizer < Documentation::Authorizer
+end
+```
+
+Once you have created this class, you can define a number of methods. In all your methods you can access `controller` to access the controller which requested the page. This allows you to access sessions, params or other request information. The methods you can override are as follows:
+
+* `can_use_ui?` - whether the built-in UI can be used
+* `can_search?` - whether searching can take place
+* `can_view_page?(page)` - whether the provided page can be viewed
+* `can_add_page?(page)` - whether a page can be created within the provided page
+* `can_reposition_page?(page)` - whether pages within the provided page can be repositioned
+* `can_edit_page?(page)` - whether the provided page can be edited
+* `can_delete_page?(page)` - whether the provided page can be deleted
+* `can_upload?(page)` - whether a file can be uploaded to this page
+
+The default for all these method if left un-defined, is `true`. Here's an example:
+
+```ruby
+def can_edit_page?(page)
+  controller.request['rack.current_user'].admin?
+end
+```
+
+## Using your authorizer class
+
+Once you have created your class, you should tell Documentation that it should use it. Do this by adding the following to your `config/initializers/documentation.rb` file`.
+
+```ruby
+Documentation.config.authorizer = MyDocsAuthorizer
+```

data/doc/developers-guide/building-views/accessing-pages.md

@@ -0,0 +1,38 @@
+Everything you need to access the pages stored in the database can be found on the `Documentation::Page` model.
+
+## Finding pages
+
+In most cases, you'll want to find a page based on its path from the root of the site, for example, `example/page/here` may be the string you want to use to find the `here` page.
+
+```ruby
+page = Documentation::Page.find_from_path('example/page/here')
+```
+
+## Useful page methods
+
+Once you've found a page, there are a number of methods & attribute which may be useful to you.
+
+* `title` - the page's title
+* `content` - the markdown content for a page
+* `compiled_content` - the HTML content for a page
+* `parents` - returns an array of all the parents for the page
+* `breadcrumb` - returns the items which should be included in a breadcrumb trail
+* `full_permalink` - the full permalink including all parents
+* `children` - all child pages for the page
+* `has_children?` - whether or not the page has children
+* `navigation` - appropriate navigation pages for this page
+
+## Searching
+
+If you wish to search pages, you should use the `Documentation::Page.search` method as shown below:
+
+```ruby
+result = Documentation::Page.search('query here', :page => 1)
+```
+
+Once you have a result object, you can use this to get information about the pages which matched the result. The following methods may be useful:
+
+* `results` - the pages which have been found
+* `excerpt_for(page)` - an excerpt to display for this page
+* `empty?` - was the search empty?
+* `total_pages` - the total number of pagination pages 

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

@@ -0,0 +1,105 @@
+All the helpers needed to do this are provided for you and are shown below. These are the same helpers which are used in the built-in interface.
+
+-------------
+
+### `documentation_breadcrumb_for(page)`
+
+This helper will return an unordered list containing a breadcrumb trail for the page you provide. The output will look something like this:
+
+```html
+<nav class='breadcrumb'>
+  <ul>
+    <li><a href='/'>Home</a></li>
+    <li><a href='/example'>Example</a></li>
+    <li><a href='/example/page'>Page</a></li>
+  </ul>
+</nav>
+```
+
+#### Options for this helper
+
+* `:class` - allows you to set the class for the outer nav element. Defaults to 'breadcrumb'.
+* `:root_link` - sets the text for the first link in the breadcrumb. Defaults to 'Home' (taken from the i18n). Set to false to exclude this item.
+
+-------------
+
+### `documentation_navigation_tree_for(page)`
+
+Provides a single-level nested unordered list which contains the given page. If the given page has no children, its parents will be included. If it has children, they will be shown too. The active page will include the `active` class.
+
+```html
+<ul>
+  <li><a href='/example'>Example Section</a></li>
+  <li>
+    <a href='/food'>Information about food</a>
+    <ul>
+      <li><a href='/foot/fruit'>Fruit</a></li>
+      <li><a href='/foot/vegetables' class='active'>Vegetables</a></li>
+      <li><a href='/foot/meat'>Meat</a></li>
+    </ul>
+  </li>
+  <li><a href='/drink'>Information about drink</a></li>
+</ul>
+```
+
+-------------
+
+### `documentation_content_for(page)`
+
+Renders the content for a given page. This will deal with ensuring that the page is unescaped and that any formatting options are correctly parsed.
+
+-------------
+
+### `documentation_authorizer`
+
+Returns the documentation authorizer.
+
+-------------
+
+### `documentation_edit_page_path(page)`
+
+Returns the path to edit the given page in the provided UI.
+
+-------------
+
+### `documentation_page_path(page)`
+
+Returns the path to view the given page in the provided UI.
+
+-------------
+
+### `documentation_search_summary(result)`
+
+Returns information about your search result
+
+-------------
+
+### `documentation_search_results(result, options)`
+
+Return an unordered list containing your search results.
+
+```html
+<ul class='searchResults'>
+  <li>
+    <h4><a href='path/to/page'>Title of page</a></h4>
+    <p class='in'><!--- Other pages if they exist --></p>
+    <p class='except'>An excerpt goes <mark>here</mark></p>
+  </li>
+</ul>
+```
+
+#### Options for this helper
+
+* `:class` - the class for the outer list
+
+-------------
+
+### `documentation_search_pagination(result, options)`
+
+Return a next page and previous page link based on the results
+
+#### Options for this helper
+
+* `:link_class` - the class to apply to both links
+* `:next_link_class` - the class for the next link
+* `:previous_link_class` - the class for the previous link