Can I get my README.textile into my RDoc with proper formatting?

笑着哭i 提交于 2019-12-06 03:02:39

问题


I like to use Textile or Markdown to write readme files for my projects, but when I generate the RDoc the readme file gets interpreted as RDoc and looks really horrible. Is there a way to make RDoc run the file through RedCloth or BlueCloth instead of its own formatter? Can it be configured to autodetect the formatting from the file suffix? (e.g. README.textile gets run through RedCloth, but README.mdown gets run through BlueCloth)


回答1:


Using YARD instead of RDoc directly will let you include Textile or Markdown files so long as their file suffixes are reasonable. I often use something like the following Rake task:

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:


If you host your project on github you can also use http://rdoc.info to automatically build and publish your rdocs using YARD.




回答3:


I realize the code in 26819 was preceded by "something like", but there are issues I ran into. My edits to the answer were rejected, so here is a fixed version (edits are commented):

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


来源:https://stackoverflow.com/questions/2138427/can-i-get-my-readme-textile-into-my-rdoc-with-proper-formatting

标签
易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!