Tôi có thể lấy README.textile vào RDoc của tôi với định dạng thích hợp không?

Question

Tôi thích sử dụng Dệt may hoặc Đánh dấu để viết các tệp readme cho các dự án của mình, nhưng khi tôi tạo RDoc, tệp readme được hiểu là RDoc và trông thực sự khủng khiếp. Có cách nào để làm cho RDoc chạy các tập tin thông qua RedCloth hoặc BlueCloth thay vì định dạng riêng của mình? Nó có thể được cấu hình để tự động phát hiện định dạng từ hậu tố tập tin không? (ví dụ: README.textile được chạy qua RedCloth, nhưng README.mdown được chạy qua BlueCloth)

Answer 1

Sử dụng YARD thay vì RDoc trực tiếp sẽ cho phép bạn bao gồm tệp Dệt hoặc Đánh dấu miễn là hậu tố tệp của họ là hợp lý. Tôi thường sử dụng một cái gì đó giống như nhiệm vụ Rake sau:

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

Nếu bạn lưu trữ dự án của bạn trên github bạn cũng có thể sử dụng http://rdoc.info để tự động xây dựng và công bố rdocs bạn sử dụng YARD.

Answer 3

Tôi nhận ra mã trong 26819 được bắt đầu bằng "cái gì đó như", nhưng có những vấn đề tôi gặp phải. Các chỉnh sửa của tôi đối với câu trả lời đã bị từ chối, vì vậy đây là phiên bản cố định (các chỉnh sửa được nhận xét):

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