Puis-je obtenir mon README.textile dans mon RDoc avec le bon formatage?
Question
J'aime utiliser pour écrire des fichiers readme pour mes projets textiles ou Markdown, mais quand je produis le RDoc le fichier readme est interprété comme RDoc et ressemble vraiment horrible. Y at-il un moyen de faire RDoc exécuter le fichier par RedCloth ou BlueCloth au lieu de son propre formatter? Peut-il être configuré pour détecter automatiquement la mise en forme du suffixe du fichier? (Par exemple README.textile se fasse automatiquement par RedCloth, mais README.mdown se fasse automatiquement par BlueCloth)
La solution
Utilisation au lieu de RDoc va directement vous permettent d'inclure des fichiers textiles ou Markdown tant que leurs extensions de fichier sont raisonnables. J'utilise souvent quelque chose comme la tâche Rake suivant:
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
Autres conseils
Je réalise le code 26819 a été précédée par « quelque chose comme », mais il y a des problèmes je suis tombé. Mes modifications à la réponse ont été rejetées, voici donc une version fixe (les modifications sont commentées):
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