Dirk Dot Net

Creator of useful things. Based in Chiang Mai, Northern Thailand.

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:

http://wiki.rubyonrails.org/rails/pages/HowToGenerateChmForRails

Older (and possibly newer in the future) CHM files created using this technique are here: http://delynnberry.com/projects/rails-chm-documentation

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:

C:\ruby\lib\ruby\gems\1.8\gems\rails-2.0.2\lib\rails_generator\generators\components\controller\templates\controller.rb

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: http://rubyforge.org/frs/?group_id=307 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:

image

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

image

In the Existing Files step, select just HTML files:

image

Click add:

image

Navigate to the \rails\doc\api:

image

Select only the index.html file:

image

The project is created.

Go to the Contents tab:

image

Give it a name and save:

image

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:

image

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

image

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

image

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":

image

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

image

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!

del.icio.us 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 wiki.rubyonrails.org 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: http://show.samesystem.dk/public/rails-2-0-2.chm 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: http://rubyforge.org/frs/?group_id=5928 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).