Kann ich meine README.textile in meine RDoc mit der richtigen Formatierung erhalten?
Frage
Ich mag Textile oder Markdown verwenden Readme-Dateien für meine Projekte zu schreiben, aber wenn ich die RDoc die Readme-Datei generieren wird als RDoc und sieht wirklich schrecklich interpretiert. Gibt es eine Möglichkeit RDoc führen Sie die Datei durch RedCloth oder BlueCloth anstelle seines eigenen Formatierer zu machen? Kann es so konfiguriert werden, um die Formatierung aus dem Dateiendung automatisch zu erkennen? (Z README.textile wird durch RedCloth laufen, aber README.mdown wird durch BlueCloth laufen)
Lösung
Mit YARD statt RDoc lassen sich direkt Sie gehören Textile oder Markdown-Dateien, solange ihre Dateiendungen zumutbar sind. Ich habe oft so etwas wie die folgende Rake Aufgabe verwenden:
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
Andere Tipps
Wenn Sie Ihr Projekt auf Github hosten können Sie auch http://rdoc.info automatisch erstellen und veröffentlichen Sie Ihre rdocs mit HOF.
Ich stelle fest, den Code in 26819 von „so etwas wie“ vorausging, aber es gibt Fragen, die ich in lief. Meine Änderungen an der Antwort wurden abgelehnt, so ist hier eine feste Version (Änderungen sind kommentiert):
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