How to Get RDoc to Use Your README file

I was setting up a Ruby project with RDoc today and ran into a problem.

Every time RDoc ran, I saw the following:

 

                        README.rdoc:
                           clApp.rb: c.......
                     fileGenTask.rb: c...c.....
                        innoTask.rb: c..
                      javaccTask.rb: c.....
                      jjtreeTask.rb: c.....
                        ocraTask.rb: c..
                         tex2rtf.rb: c..
                      versioninc.rb: c........
                         zipTask.rb: c..
                       rakeUtils.rb:
Generating HTML...
Could not find main page README.rdoc
Could not find main page README.rdoc
Could not find main page README.rdoc
Could not find main page README.rdoc

Files:   11
Classes: 10
Modules: 0
Methods: 41
Elapsed: 2.233s

 

I searched all over Google for the answer with no luck. So I made my own…

I looked into the Rake::RDocTask documentation and found this:

  Rake::RDocTask.new do |rd|
    rd.main = "README.rdoc"
    rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
  end

 

Notice how the README file is included in rdoc_files? That is the key. Not only do you need to set the file to be used as the main page, you need to be sure the file is added to the includes list.

Here is my final implementation:

  Rake::RDocTask.new do |rd|
    rd.main = "docs/README.rdoc"
    rd.rdoc_files.include("docs/README.rdoc", "lib/**/*.rb")
  end

 

Ahh, sweet success! RDoc now finds the README file, and uses it:

                        README.rdoc:
                           clApp.rb: c.......
                     fileGenTask.rb: c...c.....
                        innoTask.rb: c..
                      javaccTask.rb: c.....
                      jjtreeTask.rb: c.....
                        ocraTask.rb: c..
                         tex2rtf.rb: c..
                      versioninc.rb: c........
                         zipTask.rb: c..
                       rakeUtils.rb:
Generating HTML...

Files:   11
Classes: 10
Modules: 0
Methods: 41
Elapsed: 2.120s