app/views/documentation/pages/index.
31 | Alternatively, you can disable this message by setting developer_tips to false in the
32 | Documentation configuration.
33 | create_root_page: Create new root page
34 | reorder_root_pages: Re-order root pages
35 |
36 | show:
37 | view_in_website: View in website
38 | last_updated: Last updated on %{timestamp}
39 |
40 | admin_buttons:
41 | new: New page
42 | edit: Edit page
43 | reorder: Re-order children
44 | delete: Delete page
45 |
46 | form:
47 | title_placeholder: Enter a title for this page
48 | content_placeholder: "Use Markdown to enter page content"
49 | permalink_placeholder: Automatically generated if left blank
50 | add_screenshot: Add Screenshot
51 | save: Save Page
52 |
53 | positioning:
54 | reorder_root_pages_title: Re-order root pages
55 | back_to_page: Back to page
56 | back_to_homepage: Back to homepage
57 |
58 | search:
59 | title: "Search results for '%{query}'"
60 | no_results: "No pages were found matching '%{query}'"
61 | next_page: Next page
62 | previous_page: Previous page
63 |
--------------------------------------------------------------------------------
/config/routes.rb:
--------------------------------------------------------------------------------
1 | Documentation::Engine.routes.draw do
2 |
3 | match 'new(/*path)', :to => 'pages#new', :as => 'new_page', :via => [:get, :post]
4 | match 'positioning(/*path)', :to => 'pages#positioning', :as => 'page_positioning', :via => [:get, :post]
5 | match 'edit(/*path)', :to => 'pages#edit', :as => 'edit_page', :via => [:get, :patch]
6 | match 'delete(/*path)', :to => 'pages#destroy', :as => 'delete_page', :via => [:delete]
7 | match 'screenshot', :to => 'pages#screenshot', :as => 'upload_screenshot', :via => [:get, :post]
8 | get 'search', :to => 'pages#search', :as => 'search'
9 | get '*path' => 'pages#show', :as => 'page'
10 | root :to => 'pages#index'
11 | end
12 |
--------------------------------------------------------------------------------
/db/migrate/20140711185212_create_documentation_pages.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | class CreateDocumentationPages < ActiveRecord::Migration[6.0]
4 |
5 | def up
6 | create_table 'documentation_pages' do |t|
7 | t.string :title, :permalink
8 | t.text :content, :compiled_content
9 | t.integer :position
10 | t.belongs_to :parent, polymorphic: true
11 | t.timestamps
12 | end
13 | end
14 |
15 | def down
16 | drop_table :documentation_pages
17 | end
18 |
19 | end
20 |
--------------------------------------------------------------------------------
/db/migrate/20140724111844_create_nifty_attachments_table.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | class CreateNiftyAttachmentsTable < ActiveRecord::Migration[6.0]
4 |
5 | def up
6 | create_table :nifty_attachments do |t|
7 | t.belongs_to :parent, polymorphic: true
8 | t.string :parent_type, :token, :digest, :role, :file_name, :file_type
9 | t.binary :data, limit: 10.megabytes
10 | t.timestamps
11 | end
12 | end
13 |
14 | def down
15 | drop_table :nifty_attachments
16 | end
17 |
18 | end
19 |
--------------------------------------------------------------------------------
/db/migrate/20140724114255_create_documentation_screenshots.rb:
--------------------------------------------------------------------------------
1 | # frozen_string_literal: true
2 |
3 | class CreateDocumentationScreenshots < ActiveRecord::Migration[6.0]
4 |
5 | def change
6 | create_table :documentation_screenshots do |t|
7 | t.string :alt_text
8 | end
9 | end
10 |
11 | end
12 |
--------------------------------------------------------------------------------
/db/seeds.rb:
--------------------------------------------------------------------------------
1 | $doc_root = File.join(File.expand_path(File.join('..', '..'), __FILE__), 'doc')
2 |
3 | def doc(*path)
4 | File.read(File.join($doc_root, *path))
5 | end
6 |
7 | guide = Documentation::Page.create(:title => "Developers' Guide", :content => doc('developers-guide', 'overview.md'))
8 | guide.children.create(:title => 'Authorization', :content => doc('developers-guide', 'authorization.md'))
9 | guide.children.create(:title => 'Search Backends', :content => doc('developers-guide', 'search-backends.md'))
10 | guide.children.create(:title => 'Customization', :content => doc('developers-guide', 'customization.md'))
11 | views = guide.children.create(:title => 'Building your own views', :content => doc('developers-guide', 'building-views', 'overview.md'))
12 | views.children.create(:title => 'Accessing Pages', :content => doc('developers-guide', 'building-views', 'accessing-pages.md'))
13 | views.children.create(:title => 'Helpers', :content => doc('developers-guide', 'building-views', 'helpers.md'))
14 |
15 | markdown = Documentation::Page.create(:title => "Using Markdown", :content => doc('markdown', 'overview.md'))
--------------------------------------------------------------------------------
/doc/developers-guide/authorization.md:
--------------------------------------------------------------------------------
1 | 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.
2 |
3 | ## Creating an authorizer class
4 |
5 | To do this, begin by creating a new class which inherits from `Documentation::Authorizer`.
6 |
7 | ```ruby
8 | class MyDocsAuthorizer < Documentation::Authorizer
9 | end
10 | ```
11 |
12 | 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:
13 |
14 | * `can_use_ui?` - whether the built-in UI can be used
15 | * `can_search?` - whether searching can take place
16 | * `can_view_page?(page)` - whether the provided page can be viewed
17 | * `can_add_page?(page)` - whether a page can be created within the provided page
18 | * `can_reposition_page?(page)` - whether pages within the provided page can be repositioned
19 | * `can_edit_page?(page)` - whether the provided page can be edited
20 | * `can_delete_page?(page)` - whether the provided page can be deleted
21 | * `can_upload?(page)` - whether a file can be uploaded to this page
22 |
23 | The default for all these method if left un-defined, is `true`. Here's an example:
24 |
25 | ```ruby
26 | def can_edit_page?(page)
27 | controller.request['rack.current_user'].admin?
28 | end
29 | ```
30 |
31 | ## Using your authorizer class
32 |
33 | 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`.
34 |
35 | ```ruby
36 | Documentation.config.authorizer = MyDocsAuthorizer
37 | ```
--------------------------------------------------------------------------------
/doc/developers-guide/building-views/accessing-pages.md:
--------------------------------------------------------------------------------
1 | Everything you need to access the pages stored in the database can be found on the `Documentation::Page` model.
2 |
3 | ## Finding pages
4 |
5 | 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.
6 |
7 | ```ruby
8 | page = Documentation::Page.find_from_path('example/page/here')
9 | ```
10 |
11 | ## Useful page methods
12 |
13 | Once you've found a page, there are a number of methods & attribute which may be useful to you.
14 |
15 | * `title` - the page's title
16 | * `content` - the markdown content for a page
17 | * `compiled_content` - the HTML content for a page
18 | * `parents` - returns an array of all the parents for the page
19 | * `breadcrumb` - returns the items which should be included in a breadcrumb trail
20 | * `full_permalink` - the full permalink including all parents
21 | * `children` - all child pages for the page
22 | * `has_children?` - whether or not the page has children
23 | * `navigation` - appropriate navigation pages for this page
24 |
25 | ## Searching
26 |
27 | If you wish to search pages, you should use the `Documentation::Page.search` method as shown below:
28 |
29 | ```ruby
30 | result = Documentation::Page.search('query here', :page => 1)
31 | ```
32 |
33 | 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:
34 |
35 | * `results` - the pages which have been found
36 | * `excerpt_for(page)` - an excerpt to display for this page
37 | * `empty?` - was the search empty?
38 | * `total_pages` - the total number of pagination pages
39 |
--------------------------------------------------------------------------------
/doc/developers-guide/building-views/helpers.md:
--------------------------------------------------------------------------------
1 | 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.
2 |
3 | -------------
4 |
5 | ### `documentation_breadcrumb_for(page)`
6 |
7 | This helper will return an unordered list containing a breadcrumb trail for the page you provide. The output will look something like this:
8 |
9 | ```html
10 |
17 | ```
18 |
19 | #### Options for this helper
20 |
21 | * `:class` - allows you to set the class for the outer nav element. Defaults to 'breadcrumb'.
22 | * `: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.
23 |
24 | -------------
25 |
26 | ### `documentation_navigation_tree_for(page)`
27 |
28 | 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.
29 |
30 | ```html
31 | An excerpt goes here
87 |#{title}
" if title 16 | s << Pygments.highlight(code, :lexer => language) 17 | end 18 | rescue 19 | "#{code}#{text}
" 59 | end 60 | 61 | end 62 | end 63 | -------------------------------------------------------------------------------- /lib/documentation/search_result.rb: -------------------------------------------------------------------------------- 1 | module Documentation 2 | class SearchResult 3 | 4 | attr_accessor :query 5 | attr_accessor :time 6 | attr_accessor :raw_results 7 | attr_accessor :results 8 | attr_accessor :page 9 | attr_accessor :per_page 10 | attr_accessor :total_results 11 | 12 | def initialize 13 | @time = nil 14 | @raw_results = {} 15 | @page = 1 16 | @total_pages = 1 17 | @per_page = nil 18 | end 19 | 20 | # 21 | # Return the pages 22 | # 23 | def results 24 | @results ||= begin 25 | results = Documentation::Page.where(:id => raw_results.keys).includes(:parent).to_a 26 | results.sort_by { |p| raw_results.keys.index(p.id) } 27 | end 28 | end 29 | 30 | # 31 | # Return the highlight string for a given page 32 | # 33 | def excerpt_for(page) 34 | if @raw_results[page.id] && hl = @raw_results[page.id][:highlights] 35 | ERB::Util.html_escape((hl.join("..."))).gsub('{{{', "").gsub("}}}", "").html_safe 36 | else 37 | page.content[0,255].gsub(/[\n\r]/, '') + "..." 38 | end 39 | end 40 | 41 | # 42 | # Is the result set empty? 43 | # 44 | def empty? 45 | self.results.empty? 46 | end 47 | 48 | # 49 | # The total number of pages in the result set 50 | # 51 | def total_pages 52 | (total_results / per_page.to_f).ceil 53 | end 54 | 55 | # 56 | # The number of the first result on the current page 57 | # 58 | def start_result_number 59 | ((page - 1) * per_page) + 1 60 | end 61 | 62 | # 63 | # The number of the last result on the current page 64 | # 65 | def end_result_number 66 | start_result_number + (results.size) - 1 67 | end 68 | 69 | # 70 | # Is this the first page of the result set? 71 | # 72 | def first_page? 73 | page == 1 74 | end 75 | 76 | # 77 | # Is this the last page of the result set? 78 | # 79 | def last_page? 80 | page == total_pages 81 | end 82 | 83 | end 84 | end 85 | -------------------------------------------------------------------------------- /lib/documentation/searchers/abstract.rb: -------------------------------------------------------------------------------- 1 | module Documentation 2 | module Searchers 3 | class Abstract 4 | 5 | attr_reader :options 6 | 7 | def initialize(options = {}) 8 | @options = options 9 | setup 10 | end 11 | 12 | # 13 | # Run whatever initial set up is needed 14 | # 15 | def setup 16 | end 17 | 18 | # 19 | # Search for a page from the index 20 | # 21 | def search(query, options = {}) 22 | [] 23 | end 24 | 25 | # 26 | # Delete a page from the index 27 | # 28 | def delete(page) 29 | false 30 | end 31 | 32 | # 33 | # Reset an index to have no data within it 34 | # 35 | def reset 36 | true 37 | end 38 | 39 | # 40 | # Add or update an page in the index 41 | # 42 | def index(page) 43 | end 44 | 45 | end 46 | end 47 | end 48 | -------------------------------------------------------------------------------- /lib/documentation/searchers/simple.rb: -------------------------------------------------------------------------------- 1 | module Documentation 2 | module Searchers 3 | class Simple < Documentation::Searchers::Abstract 4 | 5 | def search(query, options = {}) 6 | # Default options 7 | options[:page] ||= 1 8 | options[:per_page] ||= 15 9 | 10 | # Query string 11 | query_string = "content LIKE ? OR title LIKE ?", "%#{query}%", "%#{query}" 12 | 13 | # Get the total number of pages 14 | total_results = pages = Documentation::Page.where(query_string).count 15 | 16 | # Get the actual pages 17 | pages = Documentation::Page.where(query_string) 18 | pages = pages.offset((options[:page].to_i - 1) * options[:per_page].to_i) 19 | pages = pages.limit(options[:per_page].to_i) 20 | 21 | # Create a result object 22 | result = Documentation::SearchResult.new 23 | result.page = options[:page].to_i 24 | result.per_page = options[:per_page].to_i 25 | result.total_results = total_results 26 | result.query = query 27 | result.time = 0 28 | result.results = pages 29 | 30 | # Return the result 31 | result 32 | end 33 | 34 | def index(page) 35 | true 36 | end 37 | 38 | end 39 | end 40 | end 41 | -------------------------------------------------------------------------------- /lib/documentation/version.rb: -------------------------------------------------------------------------------- 1 | # frozen_string_literal: true 2 | 3 | module Documentation 4 | 5 | VERSION = '3.0.0' 6 | 7 | end 8 | -------------------------------------------------------------------------------- /lib/documentation/view_helpers.rb: -------------------------------------------------------------------------------- 1 | module Documentation 2 | module ViewHelpers 3 | 4 | # 5 | # Path to edit a page in the manager UI 6 | # 7 | def documentation_edit_page_path(page) 8 | "#{::Documentation::Engine.mounted_path}/edit/#{page.full_permalink}" 9 | end 10 | 11 | # 12 | # Path to view a page in the manager UI 13 | # 14 | def documentation_page_path(page) 15 | "#{::Documentation::Engine.mounted_path}/#{page.try(:full_permalink)}" 16 | end 17 | 18 | # 19 | # Return a breadcrumb for the given page 20 | # 21 | def documentation_breadcrumb_for(page, options = {}) 22 | options[:root_link] = options[:root_link].nil? ? t('documentation.helpers.documentation_breadcrumb_for.default_root_link') : options[:root_link] 23 | options[:class] ||= 'breadcrumb' 24 | 25 | String.new.tap do |s| 26 | s << "" 39 | end.html_safe 40 | end 41 | 42 | # 43 | # Return a default navigation tree for the given page 44 | # 45 | def documentation_navigation_tree_for(page, options = {}) 46 | active_page_type = nil 47 | items = String.new.tap do |s| 48 | if page.is_a?(::Documentation::Page) 49 | 50 | pages = page.navigation.select { |p,c| documentation_authorizer.can_view_page?(p) } 51 | 52 | pages.each do |p, children| 53 | s << "{{nav}}
") do 102 | children = page.children 103 | children = children.select { |c| documentation_authorizer.can_view_page?(c) } 104 | items = children.map { |c| "You may have mistyped the address or the page may have moved.
63 |If you are the application owner check the logs for more information.
65 |Maybe you tried to change something you didn't have access to.
63 |If you are the application owner check the logs for more information.
65 |If you are the application owner check the logs for more information.
64 |