Question

When I run rake doc:app in my Rails application root, the API docs are generated using /doc/README_FOR_APP as the home page. I would like to add a .rdoc extention to that file so it is properly rendered on GitHub. Even better, I would like to move it to the app root (/README.rdoc). Is there a way to do this in my Rakefile by modifying the included rake/rdoctask task? Is there some place it looks for the name of the home page file that can be modified? Or do I have to write a new Rake task?

Bonus question: what is the logic behind the two separate files /README and /doc/README_FOR_APP for Rails applications? Why not just one?

Answer 1

Rails rdoc task is in <rails gem folder>/lib/tasks/documentation.rake

to do what you want, take the :app task and alter it, putting it in a .rake file in your app’s /lib/tasks

#clear the doc:app task et al
Rake::Task["doc:app"].clear
Rake::Task["doc/app"].clear
Rake::Task["doc/app/index.html"].clear

namespace :doc do
  desc "Generate documentation for the application. Set custom template with TEMPLATE=/path/to/rdoc/template.rb or title with TITLE=\"Custom Title\""
  Rake::RDocTask.new("app") { |rdoc|
    rdoc.rdoc_dir = 'doc/app'
    rdoc.template = ENV['template'] if ENV['template']
    rdoc.title    = ENV['title'] || "Rails Application Documentation"
    rdoc.options << '--line-numbers' << '--inline-source'
    rdoc.options << '--charset' << 'utf-8'
    rdoc.rdoc_files.include('app/**/*.rb')
    rdoc.rdoc_files.include('lib/**/*.rb')
    rdoc.rdoc_files.include('README')
    rdoc.main = 'README'
  }
end

I’m not sure if that is exactly it, but play around with it and look at the rdoc task docs for more info.