Quick Start

RDaux creates beautiful documentation websites from markdown files. It is inspired by daux.io and uses redcarpet and pygments.rb to process github-flavored markdown files into beautiful documentation websites and supports ASCII art with help of Ditaa.

Installation

RDaux is a rubygem, install it by running the following in your shell:

> gem install rdaux

Requirements

RDaux requires Python 2.5+ for its pygments dependency and Java 1.5+ for ditaa. Make sure those tools are installed and available in the $PATH

Usage

After RDaux has been installed, you can begin using it from your cli:

> rdaux -h
Usage: rdaux [--version] [--help] command [options] [args]

Available rdaux commands are:
  serve      Dynamically serve html documentation from a given directory
  generate   Generates static html site using docs from given directory

Common options:
    -h, --help                       Show this message
    -v, --version                    Show version

As you can see, RDaux can dynamically serve documentation from your markdown sources or it can generate a static documentation website. You can determine options available to each subcommand by running:

> rdaux <subcommand> -h|--help

Supported Markup

RDaux allows you to use github-flavored markdown. And supports ASCII art using powerful Ditaa for rendering.

Examples

ASCII diagrams

ASCII diagrams are processed using Ditaa, for example, the following diagram:

```ditaa
  Front-end     :      Back-end     |    Financiele
                |                   |   Instellingen
/----------+    |    /---------\    :
|   Simyo  |    |    | CDRator |    |
|  Website |<---+--->\---------/    |
\----------/    :          ^        |
                |          |        |
                |          v        |
/----------\    |    /---------\    |
| Simone   |    |    |cYEL     |    |    /----------\
|  (IVR)   |<---+--->|   SMO   :<---+--->| Interpay |
\----------/    :    |         |    :    \----------/
                |    \---------/    | 
                |                   |
```

Will looks like the following image after rendering:

Code highlighting

You can use github-flavored markdown to highligh code sections, e.g.:

```ruby
require 'rdaux'

RDaux.start
```

Becomes:

require 'rdaux'

RDaux.start

Navigation

Navigation menu on the left is built from directories and mardown file names in the directory with documentation. For example, given the following directory structure:

docs
|-- 01_Quick_Start.md
|-- 02_Advanced_Usage.md
|-- 02_Advanced_Usage
|    |-- 01_Installation.md
|    |-- 02_Configuration.md
|    +-- 03_Customization.md
+-- 03_Contributing
     |-- 01_First_Section
     |    |-- 01_Sub_Section.md
     |    |-- 02_Second_Sub_Section.md
     |    +-- 03_Last_Sub_Section.md
     +-- 02_Second_Section.md

Would become a navigation menu with each section mapping directly to a file or directory in documentation tree:

Quick Start
Advanced Usage
    Installation
    Configuration
    Customization
Contributing
    First Section
        Sub Section
        Second Sub Section
        Last Sub Section
    Second Section

Advanced usage section will have the contents of the appropriate markdown file as well as subsections with contents of markdown files stored in the directory with the same name.