Kann ich meine README.textile in meine RDoc mit der richtigen Formatierung erhalten?

Question

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)

Answer 1

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

Answer 2

Wenn Sie Ihr Projekt auf Github hosten können Sie auch http://rdoc.info automatisch erstellen und veröffentlichen Sie Ihre rdocs mit HOF.

Answer 3

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