Question

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

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

Answer 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以获取更多信息。

Answer 2

做你想做的事：

创建新的Rails应用程序时会创建README_FOR_APP文件。该代码位于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

然后，您需要在rails-#.#.#\lib\tasks\documentation.rake中修改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源并仍然可以实现目标。

如何重命名或移动Rails的README_FOR_APP

3 个答案:

做你想做的事：

关于单独的`README_FOR_APP`和`README`文件的逻辑：

然而...