如何重命名或移动Rails的\应用程序自述文件

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

要想做你想做的事,接受:app任务并修改它,把它放在app的/lib/task s中的.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 更多信息。

做你想做的:

这个 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”文件的逻辑:

• Read ,顾名思义是 你的 具体的 Rails应用,它关注 您将要使用的类和方法 已经写好了。
• README 是 一般的 描述结构的所有Rails应用程序的文档 一个Rails应用程序和一些Web服务器设置。它的水平比 Read .

  ---

然而。。。

作为提示,我建议您保留这两个文件,不要重命名它们(不要忘记Rail的 配置上的约定 方面)。任何Rails开发人员都希望这些文件在那里,重命名它们可能会使事情变得更复杂。

此约定也可以由您的IDE使用。例如,我使用NetBeans,并且Rails项目视图被预先配置为显示某些文件。如果你移动你的 Read 文件到根目录,NetBeans将不会在项目视图中显示它,您将不得不使用文件视图,或者修改项目视图(不知道这是否可能)。

如果您在本地应用程序文件夹中创建相同的任务,例如, lib/tasks/doc.rake 定义相同的任务:

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

然后这个任务将在Rails的内置任务之后运行。因此,您不必处理Rails源,仍然可以实现您的目标。