如何重命名或移动 Rails 的 README_FOR_APP

Question

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

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

Answer 1

Rails rdoc 任务位于 /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 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 的约定优于配置方面）。任何 Rails 开发人员都会期望这些文件存在，并且重命名它们可能会使事情变得更加复杂。

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

Answer 3

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

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

那么该任务将在 Rails 的内置任务之后立即运行。因此，您不必搞乱 Rails 源，仍然可以实现您的目标。