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)
The default readme file contains the repository name and some basic instructions. The file format is 'md', which stands for Markdown documentation. It is a lightweight markup language that can be easily converted to text.
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
If you host your project on github you can also use http://rdoc.info to automatically build and publish your rdocs using YARD.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With