2.7. What's Up, RDoc?
One problem with developing against Edge Rails is that the online documentation repositories are no longer accurate. Luckily all the Rails documentation is generated automatically, and it's a snap to regenerate it locally for your purposes. You can do this with the following Rake command:
$rake doc:rails
However, if you'd like more control over the process, all you need to do is invoke the RDoc generator with some appropriate options. From the top-level directory of your Rails project, run the following command:
$ rdoc --op doc/apidocs/ -x test/ -x /railties/lib/rails_generator/generators/components/controller/templates/controller.rb --all --tab-width 2 --title 'Rails Edge API documentation'
This one will crank for as much as 5 to 10 minutes, depending on how powerful your computer is. The following table describes what you've done.
When this command is complete, you'll have all your Rails API documentation in the doc/apidocs directory. There are a couple of potential advantages to running the rdoc command directly: customization and time. The rdoc command will regenerate Rails pages only when the source has changed; the rake command will redo the entire directory each time.
The rdoc output can be customized significantly. The following table describes some other useful options.
| Command Option | Description |
|---|---|
| --exclude | Alias for -x. |
| --extension a=b | Handle document files ending in .a as if they ended in .b. This is useful if you have Ruby files with nonstandard extensions, the most common of which is probably .cgi. |
| --inline-source | Place the embedded source for documented methods in the documentation file itself. If not specified, the embedded source is placed in a pop-up window. |
| --line-numbers | Include line numbers in source code. |
| --quiet | Don't show the progress output. |
| --style url | Specify a CSS page for styles. |
| --template | Specify a directory containing rdoc template files. |
When you find a set of options you like, it's probably a good idea to store the command in a shell script so that you can easily run it again whenever you update. RDoc will only update documentation for files that have changed, so subsequent documentation updates should go much more quickly.