Get and install a new RDoc template

Question

I am using Ruby on Rails 3.0.7 and I would like to install and use a new RDoc template (instead of the default) in order to documenting my application.

I would like to choose one of following:

• http://api.rubyonrails.org/
• http://www.ruby-doc.org/core/
• ... others that you advice

So,

1. Where I can get one of the above templates?
2. How can I install that?
3. What code should I put in a .rake file to generate the documentation with the chosen template?

In few words, I am a newbie in this matters.

---

At this time in my Gemfile I have stated the following:

gem "rdoc", "~> 3.6.1"

and run the bundle install command.

---

UPDATE I for @dmarkow

I installed the horo gem and inserted the following code in a my .rake file

  RDoc::Task.new do |rdoc|
    rdoc.title    = "My Awesome docs"
    rdoc.rdoc_dir = 'doc'

    rdoc.options << '-f' << 'horo'
    rdoc.options << '--main' << 'README'
  end

If I run the command rdoc -f horo --main README.rdoc *.rdoc lib ext I get this:

file '*.rdoc' not found
file 'ext' not found
uh-oh! RDoc had a problem:

Directory doc already exists, but it looks like it isn't an RDoc directory.

Because RDoc doesn't want to risk destroying any of your existing files,
you'll need to specify a different output directory name (using the --op <dir>
option)

If I run the command rake doc:app I get this:

WARNING: Deprecated reference to top-level constant 'Task' found at: <my_application_projectfolder>/Rakefile:7:in `<top (required)>'
    Use --classic-namespace on rake command
    or 'require "rake/classic_namespace"' in Rakefile
rake aborted!
wrong number of arguments (0 for 2)

---

UPDATE II for @dmarkow

I removed the doc directory:

If I run the command rdoc -f horo --main README.rdoc *.rdoc lib ext I get this:

file '*.rdoc' not found
file 'ext' not found

No newer files.

Files:      0

Classes:    0 (0 undocumented)
Modules:    0 (0 undocumented)
Constants:  0 (0 undocumented)
Attributes: 0 (0 undocumented)
Methods:    0 (0 undocumented)

Total:      0 (0 undocumented)
  0.00% documented

In the documentation directory it creates a created.rid file.

If I run the command rake doc:app I get the same as in the following UPDATE.

What I have to do? I have still to keep the gem "rdoc", "~> 3.6.1" in my Gemfile?

Answer 1

The one used at http://api.rubyonrails.org is the "Horo" template. You can find it here, along with instructions for using it (it's installed via a gem):

https://github.com/tenderlove/horo

Answer 2

I prefer Hanna, resp Hanna-nouveau. Hanna was fine, but it is based on an old rdoc-version. Hanna-nouveau base on the original Hanna, but it works with rdoc 3 (tested with rdoc 3.12).

It looks like

You may see another example in http://gems.rubypla.net/todonotes/0.1.0/

Details can be found at https://github.com/rdoc/hanna-nouveau. The Readme contains information about installation and usage.

---

Update 2014

Hanna-nouveau does not work with rdoc 4.

What you can do: Install an old rdoc-version (I use 3.12). There is no need to uninstall the most actual version. You can call rdoc version depending:

rdoc _3.12_ -f hanna [...more options...]

With _3.12_ the rdoc-version 3.12 is loaded. With -f hanna hanna-nouveau is used.