Question

I can't understand how to instruct RDoc to parse my .rake files in lib/tasks/*.rake. I am new to RDoc but I would like to be able to document each rake command. Also it doesn't seem like the RDoc html has any mention of the text in the 'desc' field above each task. What am I doing wrong?

lib/tasks/documentation.rake

Rake::Task["doc:app"].clear
Rake::Task["doc/app"].clear
Rake::Task["doc/app/index.html"].clear

# == This should do something
# Where in rdoc do I see the 'desc' text below?
desc 'Generate RDoc documentation'
namespace :doc do
  Rake::RDocTask.new('app') do |rdoc|
    rdoc.rdoc_dir = 'doc/app'
    rdoc.title    = 'Appname'
    rdoc.main     = 'doc/README_FOR_APP' # define README_FOR_APP as index

    rdoc.options << '--charset' << 'utf-8'
    rdoc.options << '--verbose'

    rdoc.rdoc_files.include('lib/**/*.rake') # just look at rakes for this example...
    rdoc.rdoc_files.include('doc/README_FOR_APP')

  end
end

lib/tasks/mp3_task.rake

require 'download/mp3_download.rb'

# This task calls the download_mp3() function
desc "Download Mp3"
task :download_mp3 => :environment do

  # Here is where I log to stdout
  puts 'in Download mp3 rake'

  clip = Clip.find(clipId)

  # This downloads the file and returns a tuple
  path, filename = downloadMp3(clip.episode.url)
end

Then I run 'rake doc:app' and get this output:

Parsing sources...
 20% [ 1/ 5]  lib/tasks/documentation.rake                                      
 40% [ 2/ 5]  lib/tasks/mp3_tasks.rake                                          
 60% [ 3/ 5]  lib/tasks/scrape_tasks.rake                                       
 80% [ 4/ 5]  lib/tasks/twitter_tasks.rake                                      
100% [ 5/ 5]  doc/README_FOR_APP                                                


Generating Darkfish format into /Users/y/railsapp/doc/app...

Files:      5

Classes:    0 (0 undocumented)
Modules:    0 (0 undocumented)
Constants:  0 (0 undocumented)
Attributes: 0 (0 undocumented)
Methods:    0 (0 undocumented)

Total:      0 (0 undocumented)
  0.00% documented

Elapsed: 0.2s

The final html is so empty it's pathetic. I don't even get functions to show in .rake files. Am I puting docs in the wrong place? It seems that they should live next to the rake task definitions, right?

No correct solution

Licensed under: CC-BY-SA with attribution
Not affiliated with StackOverflow
scroll top