Posso avere il mio README.textile nel mio RDoc e formattata?

Question

Mi piace usare Textile o Markdown per scrivere i file readme per i miei progetti, ma quando ho generare il RDoc il file readme verrà interpretato come RDoc e sembra davvero orribile. C'è un modo per rendere RDoc eseguire il file tramite RedCloth o BlueCloth invece di un proprio formattatore? Può essere configurato per rilevare automaticamente la formattazione dal suffisso del file? (Ad esempio README.textile viene eseguito tramite RedCloth, ma README.mdown viene eseguito tramite BlueCloth)

Answer 1

invece di RDoc direttamente vi permetterà di includere tessile o Markdown file in modo fino a quando i loro suffissi dei file sono ragionevoli. Io uso spesso qualcosa come il seguente compito Rastrello:

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

Se si ospita il progetto su GitHub è anche possibile utilizzare http://rdoc.info per costruire e pubblicare automaticamente il tuo rdocs con YARD.

Answer 3

Mi rendo conto che il codice 26819 è stata preceduta da "qualcosa di simile", ma ci sono problemi che ho incontrato. Le mie modifiche alla risposta sono stati respinti, ecco una versione fissa (le modifiche sono commentati):

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