Могу ли я получить README.textile в свой RDoc с правильным форматированием?

Question

Мне нравится использовать Textile или Markdown для записи файлов readme для моих проектов, но когда я создаю RDoc, файл readme интерпретируется как 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