如何使用markdown文件作为rdoc的主文件(在rails项目中)？

Question

是否可以将readme.md文件与Rails项目一起使用并将rdoc用作主页？我尝试按如下方式设置我的rake任务,但生成的index.html页面有一个占位符句子.如果我更改为README.rdoc它按预期工作,包括文件的内容.

我也在尝试使用tomdoc,我猜这可能使事情变得复杂,不确定.

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

这并不是解决问题的真正方法，但是如果您想要一个好的选择：

使用YARD

并使用以下提示：

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

我想你想使用README.md来兼容Github，我经常遇到同样的问题。所以这是一个很好的选择。性格方面我更喜欢YARD来记录我的ruby代码，它更强大，并且实际上与rubygems完全兼容，这是首选的方式。

给它扩大您的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

别忘了捆绑（更新您的Gemfile）