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:
- Download the Rails Project files from here: http://rubyforge.org/frs/?group_id=307 and unzip to your hard drive.
- Download HTML Help Workshop and install (which you need for the above rdoc technique as well).
- 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
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
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).