如何：生产CHM版的Rails手册

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:in `open’
        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:in `each’
        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:in `generate_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:in `generate’
        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:

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 <folder you unzipped rails to>\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):

• Chamonix - OS X

• Chmox - OS X

• GnoCHM - Linux

• KchmViewer - Linux

 

 

http://dirk.net/2007/12/30/generate-ruby-on-rails-chm-documentation/