Как переименовать или переместить Rails в README_FOR_APP

Question

Когда я запускаю rake doc:app в корне приложения Rails, документы API генерируются с использованием /doc/README_FOR_APP в качестве домашней страницы. Я хотел бы добавить расширение .rdoc в этот файл, чтобы оно правильно отображалось на GitHub. Еще лучше, я хотел бы переместить его в корень приложения (/README.rdoc). Есть ли способ сделать это в моем Rakefile, изменив включенную задачу rake/rdoctask? Есть ли место, где он ищет имя файла домашней страницы, который можно изменить? Или мне нужно написать новое задание Rake?

Дополнительный вопрос: какова логика двух отдельных файлов /README и /doc/README_FOR_APP для приложений Rails? Почему не только один?

Answer 1

Чтобы делать то, что вы хотите:

Файл README_FOR_APP создается при создании нового приложения Rails. Этот код в rails-#.#.#\lib\rails_generator\generators\applications\app\app_generator.rb.

Чтобы добавить суффикс и изменить местоположение для всех ваших приложений Rails, вы можете изменить метод так:

def create_documentation_file(m)
  # was m.file "doc/README_FOR_APP", "doc/README_FOR_APP"
  m.file "doc/README_FOR_APP", "README_FOR_APP.rdoc" 
end

Затем вам нужно изменить задачу документации Rake, чтобы включить этот файл, а не старый, в rails-#.#.#\lib\tasks\documentation.rake:

Rake::RDocTask.new("app") { |rdoc|
  ...
  rdoc.rdoc_files.include('README_FOR_APP.rdoc') # was 'doc/README_FOR_APP'
}

Относительно логики отдельных файлов `README_FOR_APP` и` README`:

• README_FOR_APP, как следует из названия, документация для ваше определенное приложение Rails, это касается классы и методы, которые вы будете написал.
• README is general документирование для всех приложений Rails, описывающих структуру приложения Rails и некоторые настройки веб-сервера. Это на более высоком уровне, чем README_FOR_APP. <Ч />

Однако ...

В качестве подсказки я бы посоветовал вам сохранить оба файла и не переименовывать их (не забывайте, что соглашение Rails в отношении конфигурации аспект). Любой разработчик Rails будет ожидать, что эти файлы будут там, и переименование их может усложнить задачу.

Это соглашение может также использоваться вашей IDE. Например, я использую Netbeans, и представление проекта Rails предварительно настроено для отображения определенных файлов. Если вы переместите файл README_FOR_APP в корневой каталог, NetBeans не отобразит его в представлении проекта, вам придется использовать представление файла или изменить представление проекта (даже не знаю, возможно ли это).

Answer 2

Задача Rails rdoc находится в <rails gem folder>/lib/tasks/documentation.rake

чтобы сделать то, что вы хотите, возьмите задачу: app и измените ее, поместив в файл .rake в / lib / tasks вашего приложения

#clear the doc:app task et al
Rake::Task["doc:app"].clear
Rake::Task["doc/app"].clear
Rake::Task["doc/app/index.html"].clear

namespace :doc do
  desc "Generate documentation for the application. Set custom template with TEMPLATE=/path/to/rdoc/template.rb or title with TITLE=\"Custom Title\""
  Rake::RDocTask.new("app") { |rdoc|
    rdoc.rdoc_dir = 'doc/app'
    rdoc.template = ENV['template'] if ENV['template']
    rdoc.title    = ENV['title'] || "Rails Application Documentation"
    rdoc.options << '--line-numbers' << '--inline-source'
    rdoc.options << '--charset' << 'utf-8'
    rdoc.rdoc_files.include('app/**/*.rb')
    rdoc.rdoc_files.include('lib/**/*.rb')
    rdoc.rdoc_files.include('README')
    rdoc.main = 'README'
  }
end

Я не уверен, что это именно так, но поиграйте с этим и посмотрите документацию по задачам rdoc для получения дополнительной информации.

Answer 3

Если вы создаете ту же задачу в локальной папке приложения, скажем, lib/tasks/doc.rake и определяете ту же задачу, например:

namespace :doc do
  task :app do
    # some code that adds rdoc extension
  end
end

тогда эта задача будет запущена сразу после встроенной задачи рельсов. Следовательно, вам не придется связываться с источниками рельсов и все равно достигать своей цели.