How to Rename or Move Rails's README_FOR_APP

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.

Answer 2

To do what you want:

The README_FOR_APP file is created when creating a new Rails application. That code is in rails-#.#.#\lib\rails_generator\generators\applications\app\app_generator.rb.

To add a suffix and change the location for all of your Rails apps, you can modify the method to be:

def create_documentation_file(m)
  # was m.file "doc/README_FOR_APP", "doc/README_FOR_APP"
  m.file "doc/README_FOR_APP", "README_FOR_APP.rdoc" 
end

Then, you need to modify the Rake documentation task to include this file rather than the old one, in rails-#.#.#\lib\tasks\documentation.rake:

Rake::RDocTask.new("app") { |rdoc|
  ...
  rdoc.rdoc_files.include('README_FOR_APP.rdoc') # was 'doc/README_FOR_APP'
}

Regarding the logic of separate `README_FOR_APP` and `README` files:

• README_FOR_APP, as the name implies is documentation for your specific Rails application, it concerns the classes and methods that you will have written.
• README is general documention for all Rails applications describing the structure of a Rails application and some web server settings. It's at a higher-level than README_FOR_APP.

  ---

However...

As a tip, I would advise you to keep both files and not rename them (don't forget Rail's convention over configuration aspect). Any Rails developper will expect these files to be there, and renaming them might make things more complicated.

This convention might also be used by your IDE. For example, I use Netbeans, and the Rails project view is pre-configured to display certain files. If you move your README_FOR_APP file to the root directory, NetBeans will not display it in project view, you will have to use file view, or modify the project view (don't know if that's even possible).

Answer 3

If you create same task in your local app folder in, say, lib/tasks/doc.rake and define same task like this:

namespace :doc do
  task :app do
    # some code that adds rdoc extension
  end
end

then this task would be run right after rails' built-in task. Hence you wouldn't have to mess with rails sources and still accomplish your goal.