Question

Noob here trying to figure out the simple task of adding a page to my RDoc documentation. If I do rake doc:app and view a page, then there is a sidebar that says “Pages” with README_FOR_APP listed. All I want to do is create a page named “Cheatsheet” that will appear under “Pages.” How do I create a documentation page and tell RDoc to include the new page?

Answer 1

IMO it’s a bit convoluted. Here’s the references I used:

• http://rake.rubyforge.org/classes/Rake/RDocTask.html
• How to Rename or Move Rails's README_FOR_APP

Nutshell version:

Take the “app” task from your rails library directory, for example I tested using:

~/.rvm/gems/ruby-1.9.2-p0@foo/gems/railties-3.0.9/lib/rails/tasks/documentation.rake

The part you need looks (approximately) like this:

namespace :doc do
  def gem_path(gem_name)
    path = $LOAD_PATH.grep(/#{gem_name}[\w.-]*\/lib$/).first
    yield File.dirname(path) if path
  end

  RDocTaskWithoutDescriptions.new("app2") { |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('doc/*_FOR_APP') # Modified this line
    rdoc.rdoc_files.include('app/**/*.rb')
    rdoc.rdoc_files.include('lib/**/*.rb')
  }
end

Put this in your app’s lib/tasks directory in a .rake file, e.g., doc2.rake.

Update the task name if you want to keep the original, e.g., "app2".

Update the "doc/README_FOR_APP" string to a wider pattern, or add new file(s) to process.

Create doc/Cheatsheet_FOR_APP and the new rake doc:app2 task will pick it up.