Using a rakefile to generate docs from source

Question

I downloaded the ruby Twitter gem source code and am trying to generate the documentation using yard, which I installed via gem install yard. In the rakefile, I found the following, which I assume is used to generate the docs for the Twitter gem:

require 'yard'
YARD::Rake::YardocTask.new

I tried to require yard in irb and then run YARD::Rake::YardocTask.new but nothing happened.

Can you help me get on the right track?

Hygienic

@AdamEberlin but can you confirm how I'm supposed to do it> Do I go into irb and run that command and it'll generate Twitter api docs? – Hygienic

Am I the only one who before getting to the post typed "yard rake" into google and was confused by the results? – Lithometeor

Answer 1

From the YARD docs:

The second most obvious is to generate docs via a Rake task. You can do this by adding the following to your Rakefile:

YARD::Rake::YardocTask.new do |t|
  t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
  t.options = ['--any', '--extra', '--opts'] # optional
end

both the files and options settings are optional. files will default to lib/**/*.rb and options will represents any options you might want to add. Again, a full list of options is available by typing yardoc --help in a shell. You can also override the options at the Rake command-line with the OPTS environment variable:

$ rake yard OPTS='--any --extra --opts'

To summarize: after adding YARD::Rake::YardocTask.new to your Rakefile, run rake yard.

Pilotage

Note that the block is actually optional. According to the doc, you can change the name of the task if you like. – While

But what is really OTHER_PATHS? I'm not able to include any extra files. – Nominal

@NathanLilienthal - I can only assume/hope that YARD was named for the sake of this pun. I smell a backronymic apronym... – Monk