More than just a new RDoc template
Ruby HTML CSS JavaScript
Pull request Compare This branch is 58 commits ahead of raggi:master.
Latest commit 426987b Dec 29, 2015 @Quintus Quintus Change footer link to "Hanna Nouveau".
It linked to the original Hanna RDoc template before, which is
Failed to load latest commit information.
lib Change footer link to "Hanna Nouveau". Dec 29, 2015
.gitignore Get rdoc rake task working Jun 16, 2014
Gemfile Use built-in syntax parser in ruby, instead of parser gem, Bump versi… Nov 26, 2014
LICENSE * Converted to jeweler. Dec 23, 2010
Rakefile Get rdoc rake task working Jun 16, 2014
VERSION Use built-in syntax parser in ruby, instead of parser gem, Bump versi… Nov 26, 2014


Hanna Nouveau — a better RDoc template, now for RDoc 4.

Based on the original Hanna by Mislav.

Hanna is an RDoc generator that scales. It's implemented in Haml, making the sources clean and readable. It's built with simplicity, beauty and ease of browsing in mind. (See more in the wiki.)

Hanna gem is available from

gem install hanna-nouveau

The template was created by Mislav and since then has seen contributions from:

  1. Tony Strauss, who participated from the early start and made tons of fixes and enhancements to the template;

  2. Hongli Lai with the search filter for methods.

  3. Erik Hollensbe a serious refactoring and up to date with RDoc 2.5.x and 3.x, now named 'hanna-nouveau'.

  4. James Tucker minor cleanups for Erik.


rdoc -o doc -f hanna lib/*.rb

An alternative is to set the `RDOCOPT` environment variable:

RDOCOPT="-f hanna"

This will make RDoc always use Hanna unless it is explicitly overridden.

Integrating with RubyGems

Another neat trick is to put the following line in your .gemrc, this will make RubyGems use Hanna for all rdoc generation:

rdoc: -f hanna

This will make RubyGems use Hanna when generating documentation for installed gems. Remember, if you wish to have all your gems be formatted in hanna:

gem rdoc --all --overwrite

The first time. To easily browse your newly created documentation, use:

gem server

Rake task

For repeated generation of API docs, it's better to set up a Rake task. Simply add the hanna format argument to your RDoc::Task options:

gem 'rdoc'
require 'rdoc/task' do |rdoc|
  # this only works with RDoc 3.1 or greater
  rdoc.generator = 'hanna'
  # this is what you use pre RDoc 3.1:
  rdoc.options.push '-f', 'hanna'

Tip: you can do this in the Rakefile of your Rails project before running `rake doc:rails`.

Here is an example of a task for the rdbi library:

gem 'rdoc'
require 'rdoc/task' do |rdoc|
  version = File.exist?('VERSION') ?'VERSION') : ""

  rdoc.generator = 'hanna'
  rdoc.main = 'README.rdoc'
  rdoc.rdoc_dir = 'rdoc'
  rdoc.title = "RDBI #{version} Documentation"

Modifications to RDoc

Hanna makes some small modifications to RDoc to generate more friendly documentation. First, a real parser is used for all verbatim sections, and any verbatim section that is valid ruby code will be highlighted. This is different than the RDoc default, which is to use a simple regexp with both false positives and false negatives.

Second, label lists are marked using a table instead of a description list, since it is very difficult to get visually appealing styling for description lists without cutting corners (like using fixed widths).