How do I use a markdown file as the main file for rdoc (in a rails project)?

Question

Is it possible to use a readme.md file with a Rails project and have rdoc use it a the main page? I tried setting up my rake task as follows, but the index.html page that gets generated has a placeholder sentence. If I change to README.rdoc it works as expected as includes the file's contents.

I'm also trying to use tomdoc which I guess might be complicating matters, not sure.

RDoc::Task.new :rdoc do |rdoc|
  rdoc.main = "README.md"

  rdoc.rdoc_files.include("README.md", "doc/*.rdoc", "app/**/*.rb", "lib/**/*.rb", "config/**/*.rb")

  rdoc.title = "My Documentation"
  rdoc.options << "--all"
  rdoc.options << "--line-numbers"
  rdoc.markup = "tomdoc"
  rdoc.rdoc_dir = "rdoc"
end

Answer 1

It's not really an answer to your problem, but if you want a good alternative :

use YARD

and use this tips :

https://github.com/lsegal/yard/issues/404

I presume you want to use README.md to be Github compliant, i have often the same problem. so this is a good alternative. Personnaly i prefere YARD for documenting my ruby code, it's more powerfull, and actually completely compatible with rubygems, it's the prefered way.

Give that to enlarge your Rakefile :

require "github/markup"
require "redcarpet"
require "yard"
require "yard/rake/yardoc_task"

YARD::Rake::YardocTask.new do |t|
  OTHER_PATHS = %w()
  t.files = ['lib/**/*.rb', OTHER_PATHS]
  t.options = %w(--markup-provider=redcarpet --markup=markdown --main=README.md)
end

Don't forget to bundle (update your Gemfile)