¶ ↑
Hanna-nouveauBased on the original Hanna by Mislav.
Hanna-nouveau 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.
Hanna-nouveau is distributed as a ruby gem:
gem install hanna-nouveau
The template was created by Mislav and since then has seen contributions from:
-
Tony Strauss, who participated from the early start and made tons of fixes and enhancements to the template;
-
Hongli Lai with the search filter for methods.
-
Erik Hollensbe a serious refactoring and up to date with RDoc 2.5.x and 3.x, now named 'hanna-nouveau'.
-
James Tucker minor cleanups for Erik.
-
Jeremy Evans RDoc 4 support, maintenance since 2014.
¶ ↑
Usagerdoc -o doc -f hanna lib
An alternative is to set the `RDOCOPT` environment variable:
RDOCOPT="-f hanna"
This will make RDoc always use hanna-nouveau unless it is explicitly overridden.
¶ ↑
Integrating with RubyGemsAnother 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 taskFor 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' RDoc::Task.new do |rdoc| rdoc.generator = 'hanna' end
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' RDoc::Task.new do |rdoc| version = File.exist?('VERSION') ? File.read('VERSION') : "" rdoc.generator = 'hanna' rdoc.main = 'README.rdoc' rdoc.rdoc_dir = 'rdoc' rdoc.title = "RDBI #{version} Documentation" rdoc.rdoc_files.include('README*') rdoc.rdoc_files.include('lib/**/*.rb') end
¶ ↑
Modification to RDocHanna makes a small modification to RDoc to generate more friendly documentation. It changes label lists to use 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).