Posso ottenere il mio README.textile nel mio RDoc con una formattazione corretta?

Question

Mi piace usare Textile o Markdown per scrivere file readme per i miei progetti, ma quando genero l'RDoc il file readme viene interpretato come RDoc e sembra davvero orribile. C'è un modo per far funzionare RDoc tramite RedCloth o BlueCloth invece del 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

L'utilizzo di YARD anziché RDoc consente di includere direttamente i file Textile o Markdown a condizione che i suffissi dei file siano ragionevoli. Io uso spesso qualcosa come il seguente compito 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

Se ospitate il vostro progetto su GitHub è anche possibile utilizzare http://rdoc.info per creare e pubblicare i tuoi rdocs con YARD automaticamente.

Answer 3

Mi rendo conto che il codice in 26819 è stato preceduto da "qualcosa di simile", ma ci sono problemi in cui mi sono imbattuto. Le mie modifiche alla risposta sono state respinte, quindi ecco una versione fissa (le modifiche sono commentate):

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