documentation 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7ee69981e399c23b45190208a36587d22ef937fa
-  data.tar.gz: c681d1aa01d8d237697e5fd742cfb26620f11f74
+  metadata.gz: 3ca8ff1ae21b1a4805879ab5fd9ba8872a1e4dbf
+  data.tar.gz: 2324af24ba636e1820395d9dbe23b50c8c6d0526
 SHA512:
-  metadata.gz: b73915ea29d76182c81f0b8f2aee4986bdbbf0794c08a4571817df2539405cabe4658521c31f963c053f81dac9dbc490eac724446c85f18f995a2f966b44c670
-  data.tar.gz: ac5424d483dff52ec3e1ec9dcb5a05a7e3c99a1e34282009667626972bcb59cda977251506465ac7b26c2e9492db45f3fc8bda33d152329cfc3a7493e10887b1
+  metadata.gz: 937486cd5bb4a2e0901a829f0dbbcb4cdca775ec50e3dfba7b08b0305ac8c8d17946a30cd894458b6b052e1dca46b36e58d1164379076b0bc91136e89db9a536
+  data.tar.gz: d5b492b62ce755e2f886e768c51709eb09f21298d97c4dadbab6db41cfa8c416ceb1adce696fc101b6d4b6d7e59cbc06c8bccd55783f8ce1e735f558c4a4bb9f

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

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/adamcooke/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/adamcooke/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/adamcooke/documentation)
+* [View issues](https://github.com/adamcooke/documentation/issues)
+* [Check out the installation guide](https://github.com/adamcooke/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/adamcooke/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/version.rb

@@ -1,3 +1,3 @@
 module Documentation
-  VERSION = '1.0.2'
+  VERSION = '1.0.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: documentation
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Adam Cooke
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-30 00:00:00.000000000 Z
+date: 2014-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -254,6 +254,14 @@ files:
 - db/migrate/20140724111844_create_nifty_attachments_table.rb
 - db/migrate/20140724114255_create_documentation_screenshots.rb
 - db/seeds.rb
+- doc/developers-guide/authorization.md
+- doc/developers-guide/building-views/accessing-pages.md
+- doc/developers-guide/building-views/helpers.md
+- doc/developers-guide/building-views/overview.md
+- doc/developers-guide/customization.md
+- doc/developers-guide/overview.md
+- doc/developers-guide/search-backends.md
+- doc/markdown/overview.md
 - lib/documentation.rb
 - lib/documentation/authorizer.rb
 - lib/documentation/config.rb