Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Tree: 5cdc0ce864
Fetching contributors…

Cannot retrieve contributors at this time

135 lines (98 sloc) 4.241 kB

AsciiDocWeb

AsciiDocWeb is an easy to use mountable Rails engine. It integrates your AsciiDoc generated documenation into your existing Rails project. A perfect solution in case you want to build a simple help system!

Requirements

To generate chunked output use the following command:

a2x --icons --stylesheet=custom.css -d book -vv --xsltproc-opts "--stringparam toc.section.depth 4" -f chunked toc.txt

Installation

Simply add AsciiDocWeb to your Gemfile and bundle it up:

gem 'ascii_doc_web', :git => 'git://github.com/trimentor/ascii_doc_web.git'

Run the installation generator if the default views and styles do no fit your needs:

rails g ascii_doc_web:install

Setup

Routes

Mount the AsciiDocWeb engine in your application's routes:

MyRailsApp.application.routes.draw do
  mount AsciiDocWeb::Engine => "/ascii_doc_web"
end

This line ensures that AsciiDocWeb is mounted at /ascii_doc_web.

Configuration

Create the “ascii_doc_web.yml” configuration file. This file contains all sections and manuals that should be shown to the user when he navigates to “/ascii_doc_web”.

Manuals must be categorized using sections. Provide a meaningful title for each group of manuals and a brief summary of each manual by using the title and description key.

To change the order of appearance simply addapt the configuration file.

Create a directory “manuals” inside your public folder and move all your chunked files into sub-folders.

Example

Your configuration file looks like

manuals:
  - example_guides:
      title: "Title for Section 1"
      guides:
        - example1:
          dir: "example1"
          description: "A description for example1"
        - example2:
          dir: "example2"
          description: "A description for example2"

  - example_guides2:
      title: "Title for Section 2"
      guides:
        - example3:
          dir: "example3"
          description: "A description for example3"
        - example4:
          dir: "example4"
          description: "A description for example4"

and your public folder should look like this

public/
  manuals/
    example_guides/
      example1/
        toc.chunked/
          index.html
          ch01.html
          ..
      example2/
        toc.chunked/
          index.html
          ch01.html
          ..
    example_guides2/
      example3/
        toc.chunked/
          index.html
          ch01.html
          ..
      example4/
        toc.chunked/
          index.html
          ch01.html
          ..

Bug Tracker

Have a bug? Please create an issue here on GitHub!

github.com/trimentor/ascii_doc_web/issues

Author

Copyright and License

Copyright 2011 Kjel Delaey

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Jump to Line
Something went wrong with that request. Please try again.