Roxie

Minimal Dox and Rocco-inspired documentation generator written in Ruby.

Installation

Add this line to your application's Gemfile:

gem 'roxie'

And then execute:

$ bundle

Or install it yourself as:

$ gem install roxie

Usage

There are a few different ways to generate documentation with Roxie. The first is through the command line, like so:

# Generates documentation for all .rb files in the current directory (recursive)
$ roxie **/*.rb

You can get a full list of the switches and commands you can use by running roxie help [COMMAND].

You can also use Roxie as a Rake task, similar to Yard. Here's an example of a simple Rakefile with a custom Roxie task:

require 'roxie/rake/task'
Roxie::Rake::Task.new(:doc) do |t|
  t.files = ['lib/**/*.rb']
  t.options = [
    '--only-tagged',
    '--force'
  ]
end

task :default => :doc

By default, the task name is roxie, but you can change it to be anything you'd like by passing in a new name to the constructor. It's also worth noting that t.files can be a Rake::FileList.

Finally, you can use Roxie by itself as a normal Ruby gem. Here's a sample snippet that will extract all the comments from the tiny JavaScript string:

require 'roxie'

js = <<-JS
  /**
   * Escape the given `html`.
   *
   * Examples:
   *
   *     utils.escape('<script></script>')
   *     // => '&lt;script&gt;&lt;/script&gt;'
   *
   * @param {String} html string to be escaped
   * @return {String} escaped html
   * @api public
   */

  exports.escape = function(html){
    return String(html)
      .replace(/&(?!\w+;)/g, '&amp;')
      .replace(/</g, '&lt;')
      .replace(/>/g, '&gt;');
  };
JS

Roxie.extract(js, :language => 'JavaScript')

# => [
#   {
#     :description => "Escape the given `html`.\\n\\nExamples:\\n\\n    utils.escape('<script></script>')\\n    // => '&lt;script&gt;&lt;/script&gt;'",
#     :tags => [
#       {
#         :type => "param",
#         :description => "{String} html string to be escaped"
#       },
#       {
#         :type => "return",
#         :description => "{String} escaped html"
#       },
#       {
#         :type => "api",
#         :description => "public"
#       }
#     ],
#     :line => 14
#   }
# ]

Configuring

You can pass in a hash as the second parameter of Roxie.extract() to configure the extractor. Here are the supported options:

Option	Description
`:language`	The language of the input as specified in `languages.yml`
`:only_tagged`	Only extract comments that have `@tags` in them
`:only_single`	Only extract single-line comments
`:only_multi`	Only extract multi-line comments

Note

Roxie itself does very little by design. I wanted something language-agnostic that I could use to feed into a custom Middleman site. As a result, the only functionality Roxie includes is extracting @tags from comment blocks. Beyond that, how you display your documentation is completely up to you.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request