RubyGems Integration with YARD 0.2.3.1

Just yesterday, thanks to Nick Quaranto and his GemCutter project, I discovered that RubyGems 1.3.2 introduced a new plugin architecture that developers can use to add functionality to gem. I’ve wanted to add YARD integration into RubyGems for the longest time, but I never really had any clue how to do it until now. It was actually quite simple.

YARD 0.2.3.1 is an intermediary experimental release that you won’t find on Rubyforge for now^†, but it is hosted on GemCutter, so just add the source in your gem install:

gem install yard -s http://gemcutter.org

You can also follow it on Github in yard’s rubygems-plugin branch.

^† I'm not releasing a new gem on Rubyforge because I just wrote the code about an hour ago, and considering it can theoretically mess up the way RubyGems works I'd rather not make people angry if there are any ridiculous bugs. You can, however, expect this code to be in YARD's next official release.

The Fun Stuff

The plugin basically allows for any gem that asks to be generated with YARD instead of RDoc. It generates with the same commands (gem rdoc GEMNAME) and also works with the gem doc server, so everything is neatly integrated without changing anything but one or two lines in the gemspec.

Here’s how it works with my mailer gem mmmail:

$ sudo gem install mmmail -s http://gemcutter.org
Successfully installed mmmail-1.0.0
1 gem installed
Installing YARD documentation for mmmail-1.0.0...
$ gem server
Starting gem server on http://localhost:8808/

Now we can find mmmail among our RDocs:

The RDoc link brings us to our YARD documentation!

RubyGems Deprecates has_rdoc=false?

I just want to rant on one last topic here. RubyGems maintainer Eric Hodel apparently deprecated the use of has_rdoc = false in a gemspec.

2009-05-04 Eric Hodel <…>

• lib/rubygems/rubygems_version.rb: 1.3.3.
• doc/release_notes/rel_1_3_3.rdoc: RubyGems 1.3.3 release notes.
• lib/rubygems/specification.rb: Default has_rdoc to true, ignore its value.
• lib/rubygems/doc_manager.rb: Always generate RDoc regardless of #has_rdoc?

Apparently there’s no longer a use case for not wanting to wait the ridiculous amount of time RDoc takes to generate documentation when installing a gem. This can take minutes for some gems (rails), and when you have tons of dependencies it’s a huge waste of time. Most people use the web to look at the latest up-to-date docs, not the gem server, and if they really needed them generated, gem rdoc exists.

I don’t see the point of removing functionality that has a valid use-case. Forcing a user to generate docs they are unlikely to look at is a waste of everybody’s time. If a gem says “don’t generate my docs”, the package manager should listen. The gem knows better in this case (You’re not my real father!).

But this is telling of a larger problem with general design. When you deprecate functionality, you provide an alternative to accomplish the same task. That’s just how it works. In this case, where’s the alternative? How can I ignore generating docs that users of my gem probably won’t be looking at? Unless there’s some really awesome reason why everybody in the world should generate their own copy of documentation for every gem ever, this just doesn’t make sense.

I’m still debating whether YARD will be released with has_rdoc on, since even YARD takes significant time and I expect most people to visit http://yard.soen.ca for updated documentation. Conclusion: the YARD-RubyGems plugin reverts this deprecated behaviour. When using the YARD gem plugin, has_rdoc = false is no longer ignored.