Add new page to Rails app documentation

I learnt about rake doc:app in Rails 4.0.0 the other day. Pretty handy stuff. But, it turns out if I wanted to add, say, a CHANGES.rdoc at the same level as README.rdoc, and have it included as a page in the generated HTML output, there is no simple, built-in way to do it.

I know this because I figured out that the doc:app task is part of the railties gem. Opening up its documentation.rake file, I found this code block:

RDocTaskWithoutDescriptions.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'
  rdoc.options << '--charset' << 'utf-8'
  rdoc.rdoc_files.include('README.rdoc')
  rdoc.rdoc_files.include('app/**/*.rb')
  rdoc.rdoc_files.include('lib/**/*.rb')
}

As you can see, the task only recognizes README.rdoc in an app's top-level directory. But, if I change the code a tiny bit, then it will happily include as many .rdoc files as I create.

RDocTaskWithoutDescriptions.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'
  rdoc.options << '--charset' << 'utf-8'
  rdoc.rdoc_files.include('*.rdoc') # include all .rdoc files
  rdoc.rdoc_files.include('app/**/*.rb')
  rdoc.rdoc_files.include('lib/**/*.rb')
}

I opened up issue #11903 about this. Let's see how it goes.