我可以将我的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

Answer 2

如果你在github上托管你的项目，你也可以使用http://rdoc.info自动构建和发布你的rdocs。

Answer 3

我意识到26819中的代码前面有“类似的东西”，但我遇到了一些问题。我对答案的编辑被拒绝了，所以这里是一个固定的版本(编辑是注释的)：

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

namespace :doc do

  # edit: typically (for gems, at least), Rakefile is in the root, so ".", not ".."
  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|
      # edit: README.md is not a ruby source file - see
      # https://stackoverflow.com/questions/7907698/yard-0-7-3-fails-to-build-my-readme-in-both-markdown-and-textile
      # remove README.md from yt.files
      yt.files   = Dir.glob(File.join(project_root, 'lib', '**', '*.rb'))
      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
    #edit: doc_dir was undefined; replaced by doc_destination
    rm_r doc_destination if File.exists?(doc_destination)
  end

end