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. = [
'--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>')
* // => '<script></script>'
*
* @param {String} html string to be escaped
* @return {String} escaped html
* @api public
*/
exports.escape = function(html){
return String(html)
.replace(/&(?!\w+;)/g, '&')
.replace(/</g, '<')
.replace(/>/g, '>');
};
JS
Roxie.extract(js, :language => 'JavaScript')
# => [
# {
# :description => "Escape the given `html`.\\n\\nExamples:\\n\\n utils.escape('<script></script>')\\n // => '<script></script>'",
# :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