fauna / allison

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[http://rubyforge.org/frs/download.php/25331/evan_weaver-original-public_cert.pem]. 

If you use this software, please {make a donation}[http://blog.evanweaver.com/donate/], or {recommend 
Evan}[http://www.workingwithrails.com/person/7739-evan-weaver] at Working with Rails.

== Installation

  sudo gem install allison

== Usage
  
To use the template, just run <tt>allison</tt> with your normal RDoc options. For example:

  $ allison --title 'My RDoc' --line-numbers --main README --promiscuous *
  
Note that some options like <tt>--one-file</tt> and <tt>--diagram</tt> 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 <tt>allison 
----path</tt>. Then add something like the following to your <tt>Rakefile</tt>:
    
  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 <tt>rake rdoc</tt> to invoke the task. Also, some versions of RDoc require <tt>.rb</tt> to be appended 
to the template path.

== Sample

http://blog.evanweaver.com/files/allison_release.png

== Generating documentation for Rails

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

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

== Reporting problems

The support forum is here[http://rubyforge.org/forum/forum.php?forum_id=16451].

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

== Further resources

* http://blog.evanweaver.com/articles/2007/11/08/usability-redesign-for-the-allison-template
* http://blog.evanweaver.com/articles/2006/11/15/allison-released
* http://blog.evanweaver.com/articles/2006/11/12/allison-an-rdoc-template