Generate Ruby on Rails CHM Documentation

_Update April 21, 2008: Delynn Berry now has a new CHM file up for Rails version 2.0.2 with a much better index and fewer broken links than what I was able to create. Get it ****here_**.**

CHM (compiled HTML Help) is arguably one of the better Microsoft inventions and generating these files from Ruby on Rails documentation is should be easy using Rdoc.
A general article on the different ways of generating Rails offline documentation is here.

The Rdoc approach is described in this article:

Older (and possibly newer in the future) CHM files created using this technique are here:

These are the basic rdoc instructions:

The core command is:

rdoc -f chm -o chm_folder action rails-**

which you have to run in

**C:\ruby\lib\ruby\gems\1.8\gems\ **

(assuming c:\ruby is your ruby directory).

You might (or will likely) get this error:

rails-2.0.1/lib/rails_generator/generators/components/controller/templates/controller.rb:3:15: Expected class name or '<
<'. Got RubyToken::TkLT: "<"

This is the offending file:


You can exclude this file by altering the command like so:

rdoc -f chm -o chm_folder action* rails-* -x controller.rb

It should then run up to this point.

Generating CHM...
C:/ruby/lib/ruby/1.8/rdoc/generators/html_generator.rb:1293:in initialize': Invalid argument - classes/<.html (Errno::EINVAL) from C:/ruby/lib/ruby/1.8/rdoc/generators/html_generator.rb:1293:inopen'
from C:/ruby/lib/ruby/1.8/rdoc/generators/html_generator.rb:1293:in gen_into' from C:/ruby/lib/ruby/1.8/rdoc/generators/html_generator.rb:1289:ineach'
from C:/ruby/lib/ruby/1.8/rdoc/generators/html_generator.rb:1289:in gen_into' from C:/ruby/lib/ruby/1.8/rdoc/generators/html_generator.rb:1277:ingenerate_html'
from C:/ruby/lib/ruby/1.8/rdoc/generators/html_generator.rb:1197:in generate' from C:/ruby/lib/ruby/1.8/rdoc/generators/chm_generator.rb:38:ingenerate'
from C:/ruby/lib/ruby/1.8/rdoc/rdoc.rb:284:in `document'
from C:/ruby/bin/rdoc:62

This is quite hard to work around and some suggest you should just compile help for the action packages:*

rdoc -f chm -o chm_folder action*

which contain enough documentation to get by with most daily tasks.

Update March 2, 2008: The technique described by Michael in the comments using the command

rdoc -f chm -o chm_folder action rails- -x template/***

**works fine to create a chm file. However, I use this technique only to create the index.hhk file which I then use in the following HTML Help "manual" process, which **IMHO leads to a better linked document and nicely inlined source code:

  1. Download the Rails Project files from here: and unzip to your hard drive.
  2. Download HTML Help Workshop and install (which you need for the above rdoc technique as well).
  3. Start HTML Help Workshop and create a new project:


Give it a descriptive name (damn, is that a real wizard on the left?!; I guess those were the good old days):


In the Existing Files step, select just HTML files:


Click add:


Navigate to the \rails\doc\api:


Select only the index.html file:


The project is created.

Go to the Contents tab:


Give it a name and save:


Optionally do the same for index (I haven't had any luck generating an index file).

**Update March 2, 2008: Simply navigate to the index.hhk file generated using the **

rdoc -f chm -o chm_folder action rails- -x template/***

command. This index will work only partly and many links will be dead but many work, so...

Set the project options as follows:


Make sure the Default file is set to "index.html", not the full path:


Select "Automatically create content file (.hhc) when compiling":


I was so far unable to create an index, so checking "Include keywords from HTML files" has no effect for me.

Set "Compile full-text search information":


Fire "Save all and compile". You should get a searchable CHM file with the Rails documentation.


Here is the resulting CHM file, now with (rudimentary and flaky) index. Enjoy.

Update March 2, 2008: I've uploaded a new version of the CHM file, now with an index I generated with the technique described by Michael (see comments below). However, the index works only party, many links are broken. But it's better than nothing I guess.

And finally, some non-Windows CHM readers (thanks to Delynn Berry):

Happy New Year Everyone! Tags: Ruby on Rails, CHM

Michael Carlyon: Dirk, After playing with my homemade copy of Rails 2.0.2 CHM documentation, I found many dead links, too. It appears to be a pathing problem. I didn't pursue it to a satisfactory resolution. Like you, I was happy to have documentation I could use, even if it was incomplete. Perhaps a ruby script could be designed to deal with the dead links by searching the path tree to add all of the links to the index. I don't know. I'm pretty green in Ruby and Rails. I'm glad I was a small help to you.

MICHAEL CARLYON: I think I solved your problem with getting an index into the Windows CHM help file. I downloaded and installed HTML Help Workshop. I used your link and followed its instructions to append -x template/* to the rdoc command. In the gem folder: cd \ruby\lib\ruby\gems\1.8\gems I type the command: rdoc -f chm -o chm_folder action* rails-* -x template/* That automatically produced the desired CHM help file with the index tab. I did this on 2 systems with Windows XP Professional. One with 32-bit and one with 64-bit. The 64-bit produced an empty chm_folder. Apparently, RDOC is looking in the Program Files folder for the HTML Help Workshop folder. On XP 64-bit, the HTML Help Workshop folder in located in Program Files (x86) folder. That's where the HTML Help Workshop installer places it. I copied the HTML Help Workshop folder to the Program Files folder and tried again. Success! Thanks for your tips and hard work. Michael Carlyon

Dmitry: Thank you very much for the latest version of CHM file.

Remi: Here is my build of Rails 2.0.2 CHM documentation: It is similar in structure to the delynnberry's version.

dirk: @Michael, many thanks. I now feed the index.hhk created using your technique into the HTML Help project. Many links are dead but some work, so it's better than nothing I guess.

moiristo: I was just playing tonight with creating a chm of my own, and I was wondering why you execute rdoc with 'action* rails-*'...don't you need activerecord, activeresource and activesupport as well?

Remi: You can check out this project: There are compiled CHMs of Rails (2.0, 2.1, 2.2) and Ruby 1.8 for download.

eggiscircle: thanks for the CHM :) really did help...

dirk: @Remi: Thanks a lot, the files look splendid in my xCHM viewer (Linux).

Posted: 30 December 2007

comments powered by Disqus