Allison

A modern, pretty RDoc template.

License

Copyright 2007, 2008 Cloudburst, LLC. Licensed under the AFL 3. See the included LICENSE file.

The public certificate for this gem is here.

If you like this software, please make a donation, or recommend Evan at Working with Rails.

Installation

sudo gem install allison

Usage

To use the template, just run allison with your normal RDoc options. For example:

$ allison --title 'My RDoc' --line-numbers --main README --promiscuous *

Note that some options like --one-file and --diagram might not work well.

Extras

Rake task

You can set up a Rake task if you want. First, find the path to your local machine’s template by running allison --path. Then add something like the following to your Rakefile:

require 'rake/rdoctask'

Rake::RDocTask.new do |rdoc|
      files = ['README', 'LICENSE', 'CHANGELOG', 
               'lib/**/*.rb', 'doc/**/*.rdoc', 'test/*.rb']
      rdoc.rdoc_files.add(files)
      rdoc.main = 'README'
      rdoc.title = 'My RDoc'
      rdoc.template = '/path/to/gems/allison-2.0/lib/allison'
      rdoc.rdoc_dir = 'doc'
      rdoc.options << '--line-numbers' << '--inline-source'
end

Now you can run rake rdoc to invoke the task. Also, some versions of RDoc require .rb to be appended to the template path.

Sample

Generating documentation for Rails

If you want to generate documentation for Ruby on Rails, there is a handy trick. Rails’ RDoc tasks obey the template environment variable. For instance, to document ActiveRecord, run:

cd vendor/rails/activerecord/
template=`allison --path` rake rerdoc

Reporting problems

The support forum is here.

Patches and contributions are very welcome. Please note that contributors are required to assign copyright for their additions to Cloudburst, LLC.

Further resources