企业官网建设流程全解析

• 开发工具
• CLI

rvm docs是 RVM（Ruby enVironment Manager）提供的一站式文档生成命令，用于为当前 Ruby 解释器及其 gems 生成 ri（Ruby Interactive 索引）与 rdoc 格式的 API 文档。本指南基于 help/docs.md 并结合 scripts/docs 源码实现，完整讲解generate、generate-ri、generate-rdoc、generate-gems、rdoc_data等全部子命令的用法、底层执行逻辑与排错方法，读完即可在日常开发中快速搭建本地 Ruby 文档查阅环境。

命令总览与适用场景

rvm docs属于 RVM 的维护类命令，在 help/index.txt 中被定位为"使安装 ri 和 rdoc 文档变得更简单的工具"。其完整调用语法为：

rvm docs {generate,generate-ri,generate-rdoc,generate-gems,rdoc_data}

它解决的核心问题是：本地安装的 Ruby 和 gem 默认可能没有附带 ri/rdoc 文档，导致ri String、ri Array#each等命令查询不到内容。rvm docs可以按需补齐这些文档，支持两种使用方式：

• 对已安装的 Ruby，手动执行rvm docs系列子命令生成文档；
• 对尚未安装的 Ruby，在rvm install时附加--docs标志，让文档在安装过程中自动生成。

与文档相关的磁盘空间统计可参考rvm disk-usage docs（见 help/disk-usage.md），该命令可查看文档目录占用的存储量。

工作原理：generate_docs的分派逻辑

rvm docs generate是整个命令的汇总入口，其调度逻辑位于 scripts/docs#L115-L128：

generate_docs() { case "${rvm_docs_ruby_string}" in (*1.8.7*|*1.9.2*|*1.9.3*|*2.0.0*|jruby*|rbx*) __rvm_log_command install_rdoc_data "Installing rdoc-data" \ install_rdoc_data || return $? ;; (*) generate_ri generate_rdoc ;; esac generate_gems }

从源码可以看到两个关键事实：

1. 两类 Ruby 走不同路径：对于 1.8.7、1.9.2、1.9.3、2.0.0、JRuby、RBX 这些解释器，RVM 会跳过本地生成，改为安装rdoc-datagem 并执行rdoc-data --install（对应 scripts/docs#L107-L113 的install_rdoc_data函数，它会先切换到该 Ruby 的@globalgemset）。原文档 help/docs.md 列出的支持版本为 1.8.7、1.9.2、1.9.3、JRuby、RBX，而源码中的匹配模式还额外包含了 2.0.0，这是文档未提及的实现细节。
2. 其他 Ruby 执行完整生成流程：先generate_ri生成 ri 索引，再generate_rdoc生成 rdoc HTML 文档，最后统一执行generate_gems为所有已安装 gem 生成文档。

子命令详解与底层实现

rvm docs generate-ri：生成 ri 索引

生成当前 Ruby 的 ri 文档，供ri命令离线查询。底层实现在 scripts/docs#L66-L73：

generate_ri() { install_ruby_source ( __rvm_cd "${rvm_src_path}/$rvm_docs_ruby_string/" __rvm_log_command "generate_ri" "Generating ri documentation" run_rdoc -a --ri-site ) }

执行过程包含两个动作：

• 调用install_ruby_source（scripts/docs#L15-L25）确保$rvm_src_path/<ruby-string>下存在 Ruby 源码。若源码缺失，会先尝试fetch；若抓取失败则报错并提示rvm reinstall <ruby> --disable-binary重新安装源码版 Ruby。
• 进入源码目录后调用run_rdoc（scripts/docs#L57-L64）执行rdoc -a --ri-site，即归档全部文件并生成 ri 站点索引。run_rdoc会先调用update_rdoc（scripts/docs#L97-L105）确保rdocgem 已安装，然后探测 rdoc 是否支持-V（verbose 版本信息）标志，从而选择rdoc -V或rdoc执行。

rvm docs generate-rdoc：生成 rdoc HTML 文档

生成当前 Ruby 的 rdoc HTML 文档，可通过浏览器查阅。实现在 scripts/docs#L75-L90：

generate_rdoc() { install_ruby_source ( __rvm_cd "${rvm_src_path}/$rvm_docs_ruby_string/" if gem list | __rvm_grep ^hanna >/dev/null 2>&1 then __rvm_log_command "generate_hanna" "Generating hanna documentation" \ hanna -o "${rvm_docs_path:-"$rvm_path/docs"}/$rvm_docs_ruby_string/$rvm_docs_type" --inline-source --line-numbers --fmt=html else __rvm_log_command "generate_rdoc" "Generating rdoc documentation" \ run_rdoc -a -o "${rvm_docs_path:-"$rvm_path/docs"}/$rvm_docs_ruby_string/$rvm_docs_type" fi ) }

这与原文档"如果你安装了 hanna gem，rdoc 生成将自动使用它"的描述完全对应：源码通过gem list | grep ^hanna检测 hanna 是否已安装，若已安装则改用hanna命令，并附加--inline-source --line-numbers --fmt=html参数；否则回退到标准rdoc -a -o <docs目录>。

生成的 HTML 输出到$rvm_path/docs/<ruby-string>/<docs-type>/index.html（rvm_docs_type默认值为rdoc，见 scripts/docs#L27）。rvm docs open子命令（scripts/docs#L33-L55）会在该 index.html 存在时，按gnome-open→xdg-open→open的顺序尝试用系统浏览器打开文档；若文件缺失则提示"docs are missing, perhaps run 'rvm docs generate' first?"。

rvm docs generate-gems：为 gemset 中的全部 gem 生成文档

针对当前 gemset 下所有已安装 gem 生成 ri 与 rdoc 文档，实现在 scripts/docs#L92-L95：

generate_gems() { __rvm_log_command "generate_gems" "Generating gems documentation" \command \gem rdoc --all --ri }

它直接调用当前 Ruby 的gem rdoc --all --ri命令，一次为全部 gem 补齐文档。由于rvm docs generate的最后一步总是调用generate_gems，因此完整生成一次后，无论是 Ruby 核心 API 还是 gems 文档都会被覆盖。

rvm docs rdoc_data：安装 rdoc-data 预生成数据

该子命令直接调用install_rdoc_data（scripts/docs#L107-L113），适用于文档中提到的 1.8.7、1.9.2、1.9.3、JRuby、RBX（以及源码中额外匹配的 2.0.0）等 Ruby 版本——这些版本无需本地编译生成文档，而是安装rdoc-datagem 并使用其预打包的 rdoc 数据。流程为：切换到该 Ruby 的@globalgemset → 确保rdocgem 已安装 → 检查并安装rdoc-data→ 执行rdoc-data --install。

安装时自动生成文档：--docs系列标志

除了事后手动生成，RVM 还支持在rvm install时自动生成文档。help/install.md#L121-L125 明确列出三个相关标志：

• --docs：安装后生成 ri 文档（默认开启）；
• --rdoc|--yard：指定生成的文档类型（默认 rdoc）；
• --no-docs：禁用安装后生成 ri 文档。

这些标志在 CLI 层如何生效，可以从两处源码得到印证：

1. scripts/cli#L555-L558 中，--rdoc/--yard会被解析并写入rvm_docs_type变量，最终影响rvm docs生成文档的类型与输出目录。
2. scripts/functions/build_config#L256-L272 的__rvm_setup_compile_environment_flags_docs处理编译期文档标志：当rvm_docs_flag未开启时，会对ruby*/ree*追加--disable-install-doc编译参数，即从源码层面禁止 Ruby 安装自带文档，从而加快编译速度。注释表明该逻辑曾考虑在 macOS（开发机）上默认启用文档，但目前已统一注释掉。

安装结束后，scripts/functions/manage/ruby#L114-L117 会输出提示：若带文档编译则提示"Ruby was built with documentation, to read it try: ri String"；否则提示"Ruby was built without documentation, to build it run: rvm docs generate-ri"，直接引导用户补装文档。同理，scripts/functions/rubygems#L275-L282 在安装/升级 RubyGems 时，若rvm_docs_flag未开启，会对 RubyGems 2.2+ 传入--no-document（旧版本为--no-ri --no-rdoc），避免生成冗余的 gem 文档。

前置条件与限制

结合 scripts/docs#L6-L13 的入口校验，使用rvm docs前需注意：

• 仅支持 RVM 管理的 Ruby：脚本通过__rvm_env_string获取当前 Ruby 字符串，若为system（系统自带 Ruby）或为空，会直接报错 "Currently 'rvm docs ...' does not work with non-rvm rubies." 并退出。因此应先用rvm use <version>切换到 RVM 安装的 Ruby。
• 需要 Ruby 源码：generate-ri与generate-rdoc都要在${rvm_src_path}/<ruby-string>/下执行。若源码不存在，RVM 会尝试自动抓取；抓取失败时会提示改用rvm reinstall <ruby> --disable-binary安装带源码的版本。
• 作用于当前 Ruby / 当前 gemset：文档生成目标始终是当前rvm use选中的 Ruby 与其 gemset（generate_gems作用于当前 gemset），切换 Ruby 或 gemset 后需重新生成。

命令行补全支持

rvm docs的子命令同样纳入 RVM 的 shell 补全体系。scripts/extras/completion.bash#L256-L266 定义了补全子命令列表generate generate-ri generate-rdoc generate-gems rdoc_data，在 Bash 中输入rvm docs <Tab>即可看到候选子命令；zsh 侧则由 scripts/extras/completion.zsh/_rvm#L32 提供--docs标志的补全说明（"with install, attempt to generate ri after installation"）。

常见操作流程示例

场景一：为当前 Ruby 一次性生成全部文档（ri + rdoc + gems）：

rvm use 3.2.2 # 切换到 RVM 管理的 Ruby rvm docs generate

场景二：只需 ri 索引（适合命令行快速查询 API）：

rvm docs generate-ri ri Array#each # 生成后即可离线查询

场景三：只需 rdoc HTML（适合浏览器阅读）：

rvm docs generate-rdoc rvm docs open # 用系统浏览器打开生成的 index.html

场景四：只为当前 gemset 的 gem 生成文档：

rvm docs generate-gems

场景五：安装新 Ruby 时自动生成文档：

rvm install 3.2.2 --docs # 默认行为，安装后生成 ri rvm install 3.2.2 --rdoc # 或指定生成 rdoc 类型 rvm install 3.2.2 --no-docs # 关闭文档生成，加速编译

小结

rvm docs用一套统一的命令解决了 Ruby 与 gems 文档缺失的常见问题：generate一键覆盖全部文档类型，generate-ri/generate-rdoc/generate-gems按需分别生成，rdoc_data为特定版本 Ruby 走预编译数据捷径，open负责在浏览器中打开结果；安装阶段则由--docs/--rdoc/--yard/--no-docs标志控制文档策略，并与编译期--disable-install-doc逻辑联动。理解 scripts/docs 中的分派与回退机制后，即可根据当前 Ruby 版本和源码可用性，选择最合适的文档生成路径。

• 开发工具
• CLI