赖洪礼的 blog

This is my personal blog. For Phusion's corporate blog, please go to http://blog.phusion.nl

Censor banner | Show banner | (What's this?)

Last time I blogged about the state of Ruby on Rails documentation. Those of you who have been around long enough probably remember manuals.rubyonrails.org. Back in the days, this website was very useful. But today, it’s horribly outdated. The first manual is “Upgrading to Rails 1.0″. I don’t think I need to say more.

In fact, it was not too long ago when that website was linked from rubyonrails.org. It appears they removed the link because it’s so old. But why hasn’t that website been updated?

• It’s a database-backed web application. Only a few people have write access to the website so the general public cannot contribute.
• The content management system is horribly out of date and hasn’t had a release since 2006.

Which is a shame. Some of the manuals on that site are really good, if only they’re more up to date.

Ever since I found out that the Ruby on Rails documentation on testing is horribly out of date, I’ve felt this irresistible urge to write documentation. In truth, I had been secretly contributing more documentation. And it was not without result. I’ve been working on converting some of the manuals to Asciidoc format while updating their content at the same time. Asciidoc is the documentation formatting tool used by Git. You write documentation in plain text files, and Asciidoc can convert it for you to HTML, Docbook, PDF, Unix man pages, etc. By saving the manuals in plain text files, they can be put on the Ruby on Rails source repository, so that everybody can contribute. Asciidoc is great – the Phusion Passenger manual is also written in it.

Unfortunately Asciidoc’s default HTML output layout isn’t good enough, and Asciidoc doesn’t allow you to specify a different layout. So I’ve spent my entire Saturday hacking together a new documentation formatting tool, based on Asciidoc: Mizuho. Mizuho accepts Asciidoc input files, and generates nicely formatted HTML. Multi-page HTML output is also supported! Furthermore, the HTML layout can be customized with ERB templates.

How does the result look like? Here are some previews:

• Securing Rails applications
• A Guide to Testing Rails Applications
• The Basics of Creating Rails Plugins (a new manual written recently)

These have been generated by Mizuho with the “manualsonrails” template.

I’ve committed the new Asciidoc-formatted manuals to the docrails repository, so you are likely to see a revival of manuals.rubyonrails.org. You can find the manuals source files under railties/doc/guides/.

I’ve spent some time updating “A Guide to Testing Rails Applications”, but it’s likely still out of date. If anyone spots outdated information, please contribute a patch. Thanks.

Jeremy has recently stated his concerns about the state of Ruby on Rails documentation. It isn’t the first time that people have criticized the documentation, but it is a bit worrisome that people are apparently posting less documentation blog entries about Ruby on Rails. The Ruby on Rails website itself is also in a pretty bad shape: it has many broken links and some information is outdated. (it actually recommends FastCGI as a viable deployment platform )

But complaining and criticizing will only get one so far. The best way to improve the documentation is by… well… improving it!

What’s already being done?

People have heavily criticized api.rubyonrails.org. It’s basically just an rdoc dump, and I don’t think it’s that bad. I actually like the javadoc-style usage of frames that allows me to quickly navigate through the different classes of modules. It has no search functionality, but that’s okay because I can easily navigate. I’ve never been a fan of N00bkit or RailsBrain. They look nicer but they’re also harder to navigate because of the way they sort the classes and modules.

Then came Rails-Doc.org. I like Rails-Doc.org. No, I love Rails-Doc.org!

• Its user interface is very, very nice. I like websites that look nice because they actually invite me to read the contents.
• Its search functionality is most excellent.
• It has user comments. I know Noobkit has too, but it seems Rails-Doc.org’s is implemented better.
• It’s being actively developed. I reported a bug in its search functionality, and it was quickly resolved.
• It supports API versioning.

Apart from these, I can’t really describe why Rails-Doc.org is better. It’s a feeling. Maybe it’s because of the way it looks. It just feels more comfortable than the other API doc sites when I use it, and because of that I’m encouraged to contribute useful comments (which I have).

I’ve ditched api.rubyonrails.org completely, in favor of Rails-Doc.org. Nice job, Nodeta! Too bad I can’t use Rails-Doc.org offline.

What can you do?

Posting comments on Rails-Doc.org is nice and all, but one should ideally change the API documentation directly.

A while ago, Pratik Naik announced the docrails project. Anybody can contribute API documentation, just give Pratik a call and he’ll grant you write access to the repository. Every once in a while he reviews the changes and pushes them to the main Rails repository.

Yesterday I tried to write some functional tests for an application that I’m working on, only to find out that the Rails testing manual is outdated and that the API documentation on functional tests is almost nonexistent. So I thought, this is a good opportunity to contribute to docrails. Within a few minutes, Pratik gave me commit access and I contributed some documentation. (more) While I was at it, I also merged some of the user comments that I posted on Rails-Doc.org back to the API documentation.

So, I strongly recommend everybody to contribute. Head to http://github.com/lifo/docrails/tree/master and commit away!

Phusion Passenger 2.0.2 has been released. Please read http://blog.phusion.nl/2008/07/14/phusion-passenger-202-released/ for the announcement.

HOLY COW!!! After more than 10 years*, she’s back! Who am I talking about? She refers to herself as “the perfect, invi…” aw whatever, I’ll let her do the talking:

Why is Slayers so great? I think this comment worded it the best:

Oh, shush Zaeris. Slayers was one of THE most popular titles of the 90’s and it was a gateway anime for most people in the time because how easy it was to get started on anime by it. Same with something like Sailor Moon and Dragonball Z at the time.

The actual content of the show really doesn’t matter a damn. It’s freakin’ Slayers.

And another thing about Slayers is that it always is cheesy comedy to start, then the comedy and action builds up. Hopefully the action becomes DEAD SERIOUS like they always have.

I’ve been looking forward to Slayers Revolution for quite a while now. The past Slayers series had been a blast. (*) = Okay, so technically it has not been 10 years, but 7 years. But in my opinion Slayers Premium doesn’t count. It was enjoyable for sure, but in the end it seemed like a scam: only 30 minutes airtime? And they dare calling it a “movie”?

“OMG u broke my sword!”

Realtime weapon reparation, lv 1

“As good as new!”

One can notice that they did not change the winning formula. The first thing that I noticed when I watched Slayers for the first time was its weird character designs. (Well, maybe not so weird if you’ve been watching anime for more than 10 years…) Luckily they did not change it, and new season remains faithful to the old style. The colors are the same, even though the series is now animated with modern techniques. Lina’s still as reckless as ever, Gourry’s still dumb (actually, he may have become dumber), Zelgadis and Amelia are back, and the opening theme indicates that Xelloss will be joining the party as well, once again showing his evil powers that’s hidden behind a suspicious-yet-innocent smile.

It’s a pity that Xellos’s semi-evilness is no match compared to those of the grand masters Light and Lelouche. But maybe 2006-2007 have spoiled me too much.

No changes in the voice actors or the opening/ending themes. Lina and the OP/ED songs are still voiced by the lovely Megumi Hayashibara. Not even the humor has changed. Episode 1 features a mermaid that looks like a fish and a turtle-”gundam” with one fatal weakness. And pirates. Lots of pirates. Apparently bandits are now an endangered species.

Also, the world has decided that being Lina Inverse is now a criminal offense. What’s a poor, innocent, defenseless girl like Lina going to do when she’s faced with the situation of being arrested by an inspector while she’s eating, with 500 anti-sorceress soldiers on the outside waiting for you?
(A) Give the inspector your best smile. Look at him with an innocent face and say “please don’t arrest me inspector, I’ll do *anything* for you!” *blush*
(B) Cry cry and cry some more, and tell the inspector that you have kids to take care of, who will now be forced to wander the streets in search of their lost mother.
(C) Bribe the inspector with a pr0n magazine.
(D) Become totally pissed off and throw a fireball at the army. Innocent civilians? Damages that may cost millions in money? The possibility of having to blow up half the city? What’s that?

Oh, and did mention that Lina has become flatter than before?

I’m currently working on a Rails application. It has some non-trivial business rules, so I ended up writing test methods along the lines of:

Okaaaay….. This is what I think of that method name:

Nice boat!

Other than the mental-psychological stress as well as an unexplainable impending feeling of doom that such a long method name brings forth in our minds, one have to ask oneself whether it is morally justified to unintentionally punish whomever will ever read this code by presenting them with such a NICE BOAT, even if said person deserves it.

As much as I love RSpec, it doesn’t feel totally appropriate to use it, because then everything must start with “it”. Unfortunately not all rules in my application can be described with sentences that start with “it”. Rails edge has a solution though. You can define test methods in a declarative style ala RSpec, like this:

After staring at my test cases for the 2^32th time in a futile attempt to understand what the test method names are actually trying to tell me, I gave up and decided that it’s time to dig up a series that I’ve been trying to finish for the past 3 months. Surely only this will save me from going completely insane.

The face of un-insanity (?)

There Chu Yeow, I did what you asked me to do.

Baka baka baka! ….or maybe not.

Anyway, under the hood, the test method translates that block to:

That’s nice. But it could be nicer. I don’t want to upgrade to Edge so I decided to copy & paste the ‘test’ method from ActiveSupport edge – it’s only 6 lines. And yesterday I found out that it’s apparently possible for method names to contain arbitrary binary data, except “\0″. So you can do this:

Cool! So this means we can have RSpec-style test method names even when using Test::Unit.

So I modified the test method a little bit. Copy and paste this into your test/test_helper.rb to enjoy this:

My test method now becomes: