Using YARD with Hoe, correctly
2010 / 01 / 11 — gem, hoe, rdoc, ruby, yard
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.
$ sudo gem install hoe-yard
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.