Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

Tags:

ruby

textile

rdoc

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)

like image 945
Theo Avatar asked Jan 26 '10 09:01

Theo


People also ask

What is the format of README.md file?

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.


2 Answers

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
like image 158
James A. Rosen Avatar answered Oct 13 '22 20:10

James A. Rosen


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

like image 37
bess Avatar answered Oct 13 '22 20:10

bess