RubyGems Integration with YARD

By Loren Segal on June 06, 2009 at 613:326:436 PM

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 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

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
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:

mmmail in gem server

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 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.

Questions? Comments? Follow me on Twitter (@lsegal) or email me.