Могу ли я получить свой README.textile в мой RDoc с правильным форматированием? - PullRequest
Новая
       15

Могу ли я получить свой README.textile в мой RDoc с правильным форматированием?

5 голосов
/ 26 января 2010

Мне нравится использовать Textile или Markdown для записи файлов readme для моих проектов, но когда я генерирую RDoc, файл readme интерпретируется как RDoc и выглядит действительно ужасно. Есть ли способ заставить RDoc запускать файл через RedCloth или BlueCloth вместо его собственного средства форматирования? Можно ли настроить автоопределение форматирования по суффиксу файла? (например, README.textile запускается через RedCloth, но README.mdown запускается через BlueCloth)

Ответы [ 3 ]

7 голосов
/ 27 января 2010

Использование YARD вместо RDoc напрямую позволит вам включать файлы Textile или Markdown, если их суффиксы приемлемы Я часто использую что-то вроде следующей задачи Rake: 

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
2 голосов
/ 05 октября 2010

Если вы размещаете свой проект на github, вы также можете использовать http://rdoc.info для автоматического создания и публикации ваших rdocs с использованием YARD.

0 голосов
/ 23 апреля 2013

Я понимаю, что коду в 26819 предшествовало "что-то вроде", но есть проблемы, с которыми я столкнулся. Мои правки к ответу были отклонены, поэтому здесь исправлена ​​версия (правки комментируются): 

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
...