Rust / 系统课时
生成项目文档
生成项目文档
Cargo 可以调用 rustdoc,把源码中的公共接口和文档注释生成本地 HTML 站点。本课将从环境检查开始,生成并打开 API 文档,再通过文档测试确认页面中的示例能够编译运行。
学习目标
- 使用 Cargo 生成当前项目的 API 文档
- 定位并打开本地文档首页
- 检查文档测试并处理常见失败
前置检查
先在项目根目录确认 Cargo 与 rustdoc 可用:
cargo --version
rustdoc --version预期输出:
cargo <VERSION> (<COMMIT> <DATE>)
rustdoc <VERSION> (<COMMIT> <DATE>)版本号、提交号和日期会因本机工具链不同而变化。若命令不存在,应先安装 Rust 工具链,或确认终端已经加载 Cargo 的环境变量。
生成 API 文档
执行 cargo doc --no-deps,只为当前工作区生成文档,避免同时构建所有依赖的页面:
cargo doc --no-deps预期输出:
Documenting <CRATE_NAME> v<VERSION> (<PATH>)
Finished `dev` profile [unoptimized + debuginfo] target(s) in <TIME>生成结果位于 target/doc/。crate 名中的连字符会转换为下划线,例如包名 doc-demo 的首页通常是 target/doc/doc_demo/index.html。默认只展示公开项;需要检查私有项时可临时添加 --document-private-items。
打开并定位文档
使用下面的命令生成文档并调用系统默认浏览器打开首页:
cargo doc --open --no-deps预期结果:
浏览器打开 target/doc/<CRATE_NAME>/index.html;若文档已是最新状态,Cargo 可能只显示 Finished 信息。--open 适合本地查看,不会把文档发布到网络。无图形界面的服务器可能无法启动浏览器,此时直接复制生成目录,或通过静态文件服务器访问 target/doc/。
检查文档测试
生成页面并不代表示例一定正确。继续执行文档测试:
cargo test --doc预期输出:
Doc-tests <CRATE_NAME>
running <COUNT> tests
test <SOURCE_LOCATION> ... ok
test result: ok. <COUNT> passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in <TIME><COUNT>、<SOURCE_LOCATION> 和 <TIME> 取决于项目内容。若测试失败,优先检查文档代码块是否缺少 use 导入、类型是否已改名,以及示例是否依赖未公开的接口。
常见问题
文档中找不到某个函数时,先确认该项使用了 pub,并且所在模块也能从 crate 根公开访问。页面内容没有更新时,可重新执行 cargo doc --no-deps;仍异常时删除 target/doc/ 后再次生成。
工作区包含多个包时,可使用 cargo doc -p <PACKAGE> --no-deps 只生成指定包的文档。CI 中通常同时运行 cargo doc --no-deps 和 cargo test --doc,分别检查文档可生成与示例可执行。
本课总结
cargo doc --no-deps生成当前项目的本地 API 文档cargo doc --open --no-deps可直接打开生成后的首页cargo test --doc用于验证文档代码与当前 API 一致
下一课预告
下一课将继续整理测试与文档工作流,把文档生成和文档测试接入日常开发检查。