我可以让我的README.textile进入我的RDoc与正确的格式?
题
我喜欢用纺织或降价来写自述文件为我的项目,但是当我生成的RDoc自述文件被解释为RDoc的和看起来真的很可怕。有没有一种方法,使通过的RDoc或RedCloth运行BlueCloth文件,而不是它自己的格式吗?是否可以配置自动检测从文件后缀格式? (例如README.textile获取通过RedCloth运行,但README.mdown获取通过BlueCloth运行)
解决方案
使用 YARD 而不是RDoc的直接会让你包括纺织或降价文件,只要它们的文件后缀是合理的。我经常使用类似如下的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
其他提示
如果您在github上托管你的项目,你也可以使用 http://rdoc.info 自动构建和发布使用YARD rdocs。
我实现 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
不隶属于 StackOverflow