How to Rename or Move Rails's README_FOR_APP
When I run rake doc:app
in my Rails application root, the API docs are generated using /doc/README_FOR_APP
as the home page. I would like to add a .rdoc
extention to that file so it is properly rendered on GitHub. Even better, I would like to move it to the app root (/README.rdoc
). Is there a way to do this in my Rakefile
by modifying the included rake/rdoctask
task? Is there开发者_JAVA百科 some place it looks for the name of the home page file that can be modified? Or do I have to write a new Rake task?
Bonus question: what is the logic behind the two separate files /README
and /doc/README_FOR_APP
for Rails applications? Why not just one?
Rails rdoc task is in <rails gem folder>/lib/tasks/documentation.rake
to do what you want, take the :app task and alter it, putting it in a .rake file in your app's /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
I'm not sure if that is exactly it, but play around with it and look at the rdoc task docs for more info.
To do what you want:
The README_FOR_APP
file is created when creating a new Rails application. That code is in rails-#.#.#\lib\rails_generator\generators\applications\app\app_generator.rb
.
To add a suffix and change the location for all of your Rails apps, you can modify the method to be:
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
Then, you need to modify the Rake documentation task to include this file rather than the old one, in rails-#.#.#\lib\tasks\documentation.rake
:
Rake::RDocTask.new("app") { |rdoc|
...
rdoc.rdoc_files.include('README_FOR_APP.rdoc') # was 'doc/README_FOR_APP'
}
Regarding the logic of separate `README_FOR_APP` and `README` files:
README_FOR_APP
, as the name implies is documentation for your specific Rails application, it concerns the classes and methods that you will have written.README
is general documention for all Rails applications describing the structure of a Rails application and some web server settings. It's at a higher-level thanREADME_FOR_APP
.
However...
As a tip, I would advise you to keep both files and not rename them (don't forget Rail's convention over configuration aspect). Any Rails developper will expect these files to be there, and renaming them might make things more complicated.
This convention might also be used by your IDE. For example, I use Netbeans, and the Rails project view is pre-configured to display certain files. If you move your README_FOR_APP
file to the root directory, NetBeans will not display it in project view, you will have to use file view, or modify the project view (don't know if that's even possible).
If you create same task in your local app folder in, say, lib/tasks/doc.rake
and define same task like this:
namespace :doc do
task :app do
# some code that adds rdoc extension
end
end
then this task would be run right after rails' built-in task. Hence you wouldn't have to mess with rails sources and still accomplish your goal.
精彩评论