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

Question

是否可以在 Rails 项目中使用 readme.md 文件并让 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

这并不是您问题的真正答案，但如果您想要一个好的替代方案:

使用庭院

并使用这个提示:

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

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

用它来扩大你的 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)