如何重命名或移动Rails的README_FOR_APP

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

额外的问题:Rails应用程序的两个单独文件/README/doc/README_FOR_APP背后的逻辑是什么? 为什么不只是一个?

Rails rdoc任务位于/lib/tasks/documentation.rake

做你想做的事,拿下:app任务并改变它,把它放在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任务文档以获取更多信息。

做你想做的事:

创建新的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 

然后,您需要修改Rake文档任务以在rails-#.#.#\lib\tasks\documentation.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应用程序结构和一些Web服务器设置的所有Rails应用程序的一般文档。 它处于比README_FOR_APP更高的级别。

然而…

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

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

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

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

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