Using YARD with Hoe, correctly

When I first switched from the more traditional RDoc to YARD, I was only using the basic YARD task. In YARD 0.2.3.5, a gem plugin was added to YARD that would run yardoc on an installed gem if has_rdoc was set to "yard" in the Gem Specification. The yardoc command would also use the rdoc_options and extra_rdoc_files options from the Gem Specification.

Since I use Hoe for all my gem publishing needs, I got tired of having to specify all of this information explicitly in my Rakefiles; after all Hoe is suppose to make one's Rakefiles simple and elegant. So I took advantage of Hoe's plugin system and created a Hoe plugin to properly configure my projects for YARD.

Introducing hoe-yard, a Hoe plugin that will:

• Automatically find the README and History files, irregardless of file extension.
• Sets has_rdoc to yard.
• Sets rdoc_options.
• Sets extra_rdoc_files.
• Adds YARD and hoe-yard as development dependencies.
• Adds the yard and docs Rake tasks.

Install

$ sudo gem install hoe-yard

Usage

require 'rubygems'
require 'hoe'

Hoe.plugin :yard

Hoe.spec('my_project') do
  # ...

  # optional YARD settings
  self.yard_title = 'My Project (0.1.0)'
  self.yard_markup = :markdown
  self.yard_opts = ['--protected'] # any additional YARD options

  # ...
end

Not only does hoe-yard make setting up YARD with a project extremely easy, it also ensures the documentation that is automatically generated when a gem is installed will match the documentation published for that gem.