ruby - 我可以将我的 README.textile 以正确的格式放入我的 RDoc 中吗？

Question

我喜欢使用 Textile 或 Markdown 为我的项目编写自述文件，但是当我生成 RDoc 时，自述文件被解释为 RDoc 并且看起来非常糟糕。有没有办法让 RDoc 通过 RedCloth 或 BlueCloth 而不是它自己的格式化程序运行文件？它可以配置为自动检测文件后缀的格式吗？ (例如 README.textile 通过 RedCloth 运行，但 README.mdown 通过 BlueCloth 运行)

Answer 1

使用 YARD直接代替 RDoc 将允许您包含 Textile 或 Markdown 文件，只要它们的文件后缀是合理的。我经常使用类似于以下 Rake 任务的东西:

desc "Generate RDoc"
task :doc => ['doc:generate']

namespace :doc do
  project_root = File.expand_path(File.join(File.dirname(__FILE__), '..'))
  doc_destination = File.join(project_root, 'doc', 'rdoc')

  begin
    require 'yard'
    require 'yard/rake/yardoc_task'

    YARD::Rake::YardocTask.new(:generate) do |yt|
      yt.files   = Dir.glob(File.join(project_root, 'lib', '**', '*.rb')) + 
                   [ File.join(project_root, 'README.md') ]
      yt.options = ['--output-dir', doc_destination, '--readme', 'README.md']
    end
  rescue LoadError
    desc "Generate YARD Documentation"
    task :generate do
      abort "Please install the YARD gem to generate rdoc."
    end
  end

  desc "Remove generated documenation"
  task :clean do
    rm_r doc_dir if File.exists?(doc_destination)
  end

end