如何为（所有）Rails 生成 RDOC？答案

【问题标题】：How do I generate RDOC for (all of) Rails?如何为（所有）Rails 生成 RDOC？
【发布时间】：2010-11-15 04:21:54
【问题描述】：

我可以的

sudo gem rdoc activerecord --no-ri

和

sudo gem rdoc actionpack --no-ri

这两个都给了我很好的文档。

但是

sudo gem rdoc rails --no-ri

几乎什么也没给我，因为 Rails gem 本身实际上只是其他人的持有者。如何生成 http://api.rubyonrails.org/ 的等效项？

【问题讨论】：

标签： ruby-on-rails ruby api rdoc

【解决方案1】：

来自Rails project Rakefile

desc "Generate documentation for the Rails framework"
Rake::RDocTask.new do |rdoc|
  rdoc.rdoc_dir = 'doc/rdoc'
  rdoc.title = "Ruby on Rails Documentation"

  rdoc.options << '--line-numbers' << '--inline-source'
  rdoc.options << '-A cattr_accessor=object'
  rdoc.options << '--charset' << 'utf-8'

  rdoc.template = ENV['template'] ? "#{ENV['template']}.rb" : './doc/template/horo'

  rdoc.rdoc_files.include('railties/CHANGELOG')
  rdoc.rdoc_files.include('railties/MIT-LICENSE')
  rdoc.rdoc_files.include('railties/README')
  rdoc.rdoc_files.include('railties/lib/{*.rb,commands/*.rb,rails/*.rb,rails_generator/*.rb}')

  rdoc.rdoc_files.include('activerecord/README')
  rdoc.rdoc_files.include('activerecord/CHANGELOG')
  rdoc.rdoc_files.include('activerecord/lib/active_record/**/*.rb')
  rdoc.rdoc_files.exclude('activerecord/lib/active_record/vendor/*')

  rdoc.rdoc_files.include('activeresource/README')
  rdoc.rdoc_files.include('activeresource/CHANGELOG')
  rdoc.rdoc_files.include('activeresource/lib/active_resource.rb')
  rdoc.rdoc_files.include('activeresource/lib/active_resource/*')

  rdoc.rdoc_files.include('actionpack/README')
  rdoc.rdoc_files.include('actionpack/CHANGELOG')
  rdoc.rdoc_files.include('actionpack/lib/action_controller/**/*.rb')
  rdoc.rdoc_files.include('actionpack/lib/action_view/**/*.rb')
  rdoc.rdoc_files.exclude('actionpack/lib/action_controller/vendor/*')

  rdoc.rdoc_files.include('actionmailer/README')
  rdoc.rdoc_files.include('actionmailer/CHANGELOG')
  rdoc.rdoc_files.include('actionmailer/lib/action_mailer/base.rb')
  rdoc.rdoc_files.exclude('actionmailer/lib/action_mailer/vendor/*')

  rdoc.rdoc_files.include('activesupport/README')
  rdoc.rdoc_files.include('activesupport/CHANGELOG')
  rdoc.rdoc_files.include('activesupport/lib/active_support/**/*.rb')
  rdoc.rdoc_files.exclude('activesupport/lib/active_support/vendor/*')
end

# Enhance rdoc task to copy referenced images also
task :rdoc do
  FileUtils.mkdir_p "doc/rdoc/files/examples/"
  FileUtils.copy "activerecord/examples/associations.png", "doc/rdoc/files/examples/associations.png"
end

【讨论】：

从 /Library/Ruby/Gems/1.8/gems/rails-2.3.3/ 运行它会给我一个“找不到模板 'horo'”错误。指定一个模板（特别是 /Library/Ruby/Gems/1.8/gems/mislave-hanna-0.1.7/lib/hanna）会给我一个“RDoc::RDoc:Class 的未定义方法 `add_generator'”错误。
如果您想完全使用该脚本，则必须下载 Rails Git 存储库。
从新签出的 Rails 项目运行 rake rdoc 时，我仍然得到“RDoc::RDoc:Class 的未定义方法 `add_generator'”。
Rails 是否使用特定版本的 RDoc？我试过 2.3.0 和 2.4.3，这两个都一直在爆炸。
我相信 Rails 仍然默认使用 RDoc 1。你不能只运行：rake doc:rails ?

【解决方案2】：

如果您使用 rdoc 安装 rails (sudo gem install rails) 您可以通过

访问它

gem server

【讨论】：

【解决方案3】：

如果您需要生成边缘文档，您可以执行类似的操作

git clone git://github.com/rails/rails.git ~/rails
# or if you have repo, just checkout interested branch
cd ~
ruby ~/rails/railties/bin/rails docapp
cd docapp
ln -s ~/rails vendor/rails
rake doc:rerails
rake doc:guides

【讨论】：

【解决方案4】：

您可以在应用中冻结 Rails 并运行 rake doc:rails 以获取文档。

rails doc_project
cd doc_project
rake rails:freeze
rake doc:rails

RDocs 应该位于 doc/api 目录中。您可以使用 rake rails:freeze:edge 获取 Edge Rails 的文档。

或者，您也可以从 Rails Brain 之类的网站下载文档以获取可搜索的模板。

如果您希望文档显示在 gem server 中，那么最简单的方法可能是使用 rdoc 选项重新安装 rails gem。

sudo gem install rails --rdoc

【讨论】：

sudo gem install rails --rdoc 对我没有任何帮助。我仍然收到“找不到文件：/Library/Ruby/Gems/1.8/doc/rails-2.3.3/rdoc/index.html”。而另一种解决方案将文档放在 doc/api 目录中，而不是 gem docs 服务器可以找到的地方。

【解决方案5】：

我发现最简单的方法是从railsapi.com 下载它们并将文件解压缩到/Library/Ruby/Gems/1.8/doc/rails-2.3.3/rdoc/

【讨论】：

关于生成的问题 - 此答案用于检索。

【解决方案6】：

$ rake rails:freeze:gems
$ rake doc:rails
$ rake rails:unfreeze
$ sudo mv doc/api/* /Library/Ruby/Gems/1.8/doc/rails-2.3.5/rdoc
$ gem server

【讨论】：

【解决方案7】：

sudo gem rdoc --all --overwrite

【讨论】：

【解决方案8】：

下面是我尝试澄清有关如何将 Rails 3.1 文档本地下载到您的计算机的步骤，相当于http://api.rubyonrails.org/

转到https://github.com/voloko/sdoc 的 sdoc 项目并获取该项目（或直接执行 gem install sdoc）
访问https://github.com/rails/rails 上的rails 项目并将其git 克隆到您的本地计算机
进入 rails 克隆并运行 sdoc -N rails
这需要一段时间。完成后，您将拥有一个名为 doc 的新目录
您可以将 doc 目录移动到任何您喜欢的位置，然后在浏览器中打开 index.html 文件。请注意，您不需要网络服务器即可。

附带说明一下，sdoc 似乎已正式成为 Ruby on Rails API 的文档（请参阅 http://weblog.rubyonrails.org/2011/8/29/the-rails-api-switches-to-sdoc）

【讨论】：

【解决方案9】：

在命令行上运行命令bundle exec rdoc。

它将生成您的代码的所有文档。

【讨论】：