Dirk.Net

RSpec is the king of the BDD hill when it comes to Rails, and the learning curve is quite steep. For Windows developers hooked on CHM documentation, it’s very easy to generate RSpec CHM files by running the command

rdoc -f chm -o chm_folder rspec*

in the

/vendor/plugins

directory of your RoR project where you have installed the RSpec and RSpec on Rails plugins using

ruby script/plugin install http://rspec.rubyforge.org/svn/tags/CURRENT/rspec
ruby script/plugin install http://rspec.rubyforge.org/svn/tags/CURRENT/rspec_on_rails

as described on the RSpec home page.

The resulting CHM is not the prettiest but it’s fully searchable and easier to use than sifting through the online rdocs in your browser.

If you have trouble getting Autotest to run on Windows with `expand_path’: couldn’t find HOME environment — expanding `~/.autotest’ (ArgumentError) messages and the like, this post might help you.

So the steps are:

• gem install zentest
• Download and install diffutils from http://gnuwin32.sourceforge.net/packages/diffutils.htm
• Put the installation directory of diff.exe into your PATH in Control Panel>System>Advanced>Environment Variables
  

Then “Autotestify” your Rails app by running in the app dir:

>>set home=.

>>autotest -rails

Test away.

Update: If you still get

/site_ruby/1.8/rubygems.rb:385:in `latest_partials’: undefined method `[]‘ for nil:NilClass (NoMethodError)

or the like, make sure to remove all foreign folders from your gems folder (on Windows, usually C:\ruby\lib\ruby\gems\1.8\gems). Rubygems needs all folders in the <name>-<version> format.

One more thing: To get this working with Netbeans 6 (if you still get the couldn’t find HOME environment error), you need to create an environment variable named HOME (containing anything), quickest from the command line (if you have the Resource Pack installed with the setx command) for example

setx HOME .

and then restart Netbeans. Autotest will not load before your restart the Netbeans IDE. Hope it helps.

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

Happy New Year Everyone!

Errors like

/opt/software/ruby/gems/rails-1.2.5/lib/commands/servers/mongrel.rb:15: warning: already initialized constant OPTIONS
/opt/software/ruby/gems/rails-1.2.5/lib/commands/servers/mongrel.rb:18: undefined method `options’ for []:Array (NoMethodError)

when starting Mongrel or Webrick with ruby script/server are likely plugin related. You might be tempted to fire up the debugger, especially since the newly released Netbeans IDE makes debugging Rails apps almost enjoyable. However, the debugger is unlikely to help much here as the error messages don’t describe the actual problem, which is missing gem dependencies of some plugin.
It’s much easier and quicker to proceed as suggested in this article:
Move all plugin files from $RAILS_ROOT/vendor/plugins to a different directory. Then the web server should boot already. Then you can move the plugins back one by one and then test and see if you need any additional gems or other dependencies. Hope it helps.

The Queenslanders are storming ahead with today’s 0.9 release of Ruby.NET, now an open source community project. The new features include designer support of Windows Forms (be sure to check out this walkthrough). You might want to compare another Windows Forms approach with IronRuby and Ruby in Steel. 
If you run into error such as

The element ‘Target’ in namespace ‘http://schemas.microsoft.com/developer/msbuild/2003′ has invalid child element ‘RubyCompileTask’ in namespace ‘http://schemas.microsoft.com/developer/msbuild/2003′. List of possible elements expected: ‘Task, OnError’ in namespace ‘http://schemas.microsoft.com/developer/msbuild/2003′

you may have to remove and re-install the Visual Studio 2005 SDK as well as Ruby.NET Runtime and the Ruby.NET VS Integration. Also be sure to remove all prior versions of Ruby.NET.

For some background info on the challenges and the ingenious solutions of the QUT team read “Compiling Ruby on the CLR“. As it turns out, the difficulties lie not with the type mapping but rather with the object lifecycle and control flow prescribed by Ruby, which makes no clear distinction between compile time and runtime. The core of the challenge is harnessing the “dynamics” of Ruby with proxy classes to have them compile for the static CLR. The IronRuby approach is different (and probably somewhat easier) in that it targets the DLR (dynamic language runtime), a common type system for dynamic languages on top of the CLR also used by IronPython.

Ruby.NET project leader Wayne Kelly hints that they are “[they] are close to getting Ruby on Rails to run successfully”. This is quite exciting and having two competing (?, MS gave money to the Ruby.NET project, hopefully without strings attached) implementations on the CLR will make it harder for MS to pull a J++ on Ruby (see here, here and here), i.e. co-opting and “extending” (forking), thereby compromising competing technologies.