如何重命名或移动 Rails 的 README_FOR_APP答案

【问题标题】：How to Rename or Move Rails's README_FOR_APP如何重命名或移动 Rails 的 README_FOR_APP
【发布时间】：2010-01-15 00:36:23
【问题描述】：

当我在 Rails 应用程序根目录中运行 rake doc:app 时，API 文档是使用 /doc/README_FOR_APP 作为主页生成的。我想在该文件中添加一个 .rdoc 扩展名，以便在 GitHub 上正确呈现。更好的是，我想将其移至应用程序根目录 (/README.rdoc)。有没有办法在我的Rakefile 中通过修改包含的rake/rdoctask 任务来做到这一点？它是否在某个地方查找可以修改的主页文件的名称？还是我必须编写一个新的 Rake 任务？

额外问题：Rails 应用程序/README 和/doc/README_FOR_APP 两个独立文件背后的逻辑是什么？为什么不只有一个？

【问题讨论】：

标签： ruby-on-rails ruby rake

【解决方案1】：

Rails rdoc 任务在<rails gem folder>/lib/tasks/documentation.rake

要做你想做的事，接受 :app 任务并对其进行修改，将其放入应用程序 /lib/tasks 中的 .rake 文件中

#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 task docs 了解更多信息。

【讨论】：

是的，但是如果我重新定义了一个 Rake 任务，那么这个块就会被附加到现有的任务中。我需要一种擦除现有任务或阻止它被加载的方法（在我的 Rakefile 中注释掉 require 'rake/rdoctask' 有效，但它也摆脱了我想要的其他任务）。
抱歉，我不太了解 Rake。除了不requireing 文件之外，还有其他方法可以清除任务吗？
Rake::Task[].clear 将清除与该任务及其先决条件关联的操作。此外，您要更改的任务未在 rake/rdoctask 中定义，它是 lib 定义的默认 rake 任务。

【解决方案2】：

做你想做的事：

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 是描述结构的所有 Rails 应用程序的通用文档 Rails 应用程序和一些 Web 服务器设置。它比README_FOR_APP 更高级别。

但是……

作为提示，我建议您保留这两个文件而不是重命名它们（不要忘记 Rail 的 convention over configuration 方面）。任何 Rails 开发人员都希望这些文件存在，重命名它们可能会使事情变得更复杂。

您的 IDE 也可能使用此约定。例如，我使用 Netbeans，Rails 项目视图已预先配置为显示某些文件。如果您将README_FOR_APP 文件移动到根目录，NetBeans 将不会在项目视图中显示它，您将不得不使用文件视图，或者修改项目视图（不知道这是否可能）。

【讨论】：

【解决方案3】：

如果您在本地应用程序文件夹中创建相同的任务，例如 lib/tasks/doc.rake，并像这样定义相同的任务：

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

那么这个任务将在 Rails 的内置任务之后运行。因此，您不必弄乱 Rails 源代码，仍然可以实现您的目标。

【讨论】：