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)

Answer 1

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

Answer 2

Si vous hébergez votre projet sur GitHub, vous pouvez également utiliser http://rdoc.info pour construire automatiquement et publier votre rdocs à l'aide. YARD

Answer 3

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