5


2

適切なフォーマットでREADME.textileをRDocに取り込むことはできますか?

私はTextileまたはMarkdownを使用してプロジェクトのREADMEファイルを作成するのが好きですが、RDocを生成すると、READMEファイルはRDocとして解釈され、本当に恐ろしく見えます。 RDocが独自のフォーマッタではなくRedClothまたはBlueClothを介してファイルを実行する方法はありますか? ファイルのサフィックスからフォーマットを自動検出するように構成できますか? (例えば。 README.textileはRedClothを介して実行されますが、README.mdownはBlueClothを介して実行されます)

3 Answer


7


RDocの代わりにhttp://yardoc.org/[YARD]を直接使用すると、ファイルサフィックスが適切である限り、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


2


githubでプロジェクトをホストする場合は、http://rdoc.infoを使用して、YARDを使用してrdocsを自動的にビルドおよび公開することもできます。


0


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