icon Ruby on Rails 2.0 日记

第8章 生成 Rails 1.2 的 API 文档

在 Ruby on Rails 开发时经常得到 http://api.rubyonrails.org/ 的帮助。但是有一点为难的是，这里刊登的信息中只有最新版的 Rails 的 API 。使用老版本的 Ruby on Rails 进行开发时，老版本的文档便十分必要。

下面说明自己生成 Rails 1.2.3 的文档的步骤。（以下的是在 Linux/Mac OS X 上的步骤。Microsoft Windows 环境下省略 sudo ，将目录的分隔符 / 换成 \。）

首先查看 RubyGems 的版本。

% gem --version
1.0.1

如果 RubyGems 好像比这还旧的样子，就进行更新。

% sudo gem update --system

然后查看安装的 Rails 的版本。

% gem list rails
*** LOCAL GEMS ***

rails (2.0.2, 1.2.6, 1.2.3)

如果 1.2.3 的文字不在列表中，便指定版本安装 Rails。

% sudo gem install rails --version=1.2.3

接下来，进入适当的目录，（例：/home/kuroda/working），生成新的 Rails 程序 api。但是要注意一下没写 _1.2.3_ 的话，生成的便是最新版本（2.0.2）的程序。

% cd /home/kuroda/working
% rails _1.2.3_ api

接下来执行 Rake 任务 rails:freeze:gems 。

% cd api
% rake --require=rubygems/gem_runner rails:freeze:gems VERSION=1.2.3
(in /home/kuroda/working/api)
Freezing to the gems for Rails 1.2.3
Unpacked gem: '/home/kuroda/working/api/vendor/rails/activesupport-1.4.2'
Unpacked gem: '/home/kuroda/working/api/vendor/rails/activerecord-1.15.3'
Unpacked gem: '/home/kuroda/working/api/vendor/rails/actionpack-1.13.3'
Unpacked gem: '/home/kuroda/working/api/vendor/rails/actionmailer-1.3.3'
Unpacked gem: '/home/kuroda/working/api/vendor/rails/actionwebservice-1.2.3'
Unpacked gem: '/home/kuroda/working/api/vendor/rails/rails-1.2.3'

在这里没有添加 --require=rubygems/gem_runner 的话，便会出现下面这个错误导致中止。这个现象在0.9.5 以后的 RubyGems 发生。

% rake rails:freeze:gems VERSION=1.2.3
Freezing to the gems for Rails 1.2.3
rake aborted!
uninitialized constant Gem::GemRunner

(See full trace by running task with --trace)

这个错误只要出现一次，即使添加 --require 选项执行刚才的任务，也会因其它的错误中止。

% rake --require=rubygems/gem_runner rails:freeze:gems VERSION=1.2.3
rake aborted!
no such file to load -- /home/kuroda/working/api/config/../vendor/rails/railties/lib/initializer
/home/kuroda/working/api/Rakefile:4
(See full trace by running task with --trace)

但是，删除 vendor/rails 目录的话便回复正常。

% rmdir vendor/rails
% rake --require=rubygems/gem_runner rails:freeze:gems VERSION=1.2.3

接下来执行 Rake 任务 doc:rails 。

% rake doc:rails

doc/api 目录下生成了 index.html 之外的大量的 HTML 文件。使用浏览器打开的话 便显示出Rails 1.2.3 的 API 文档。

参考资料

（2008/03/04）