Rust / 系统课时

生成项目文档

生成项目文档

Cargo 可以调用 rustdoc,把源码中的公共接口和文档注释生成本地 HTML 站点。本课将从环境检查开始,生成并打开 API 文档,再通过文档测试确认页面中的示例能够编译运行。

学习目标

  • 使用 Cargo 生成当前项目的 API 文档
  • 定位并打开本地文档首页
  • 检查文档测试并处理常见失败

前置检查

先在项目根目录确认 Cargo 与 rustdoc 可用:

bash
cargo --version
rustdoc --version

预期输出:

text
cargo <VERSION> (<COMMIT> <DATE>)
rustdoc <VERSION> (<COMMIT> <DATE>)

版本号、提交号和日期会因本机工具链不同而变化。若命令不存在,应先安装 Rust 工具链,或确认终端已经加载 Cargo 的环境变量。

生成 API 文档

执行 cargo doc --no-deps,只为当前工作区生成文档,避免同时构建所有依赖的页面:

bash
cargo doc --no-deps

预期输出:

text
 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。

打开并定位文档

使用下面的命令生成文档并调用系统默认浏览器打开首页:

bash
cargo doc --open --no-deps

预期结果:

text
浏览器打开 target/doc/<CRATE_NAME>/index.html;若文档已是最新状态,Cargo 可能只显示 Finished 信息。

--open 适合本地查看,不会把文档发布到网络。无图形界面的服务器可能无法启动浏览器,此时直接复制生成目录,或通过静态文件服务器访问 target/doc/。

检查文档测试

生成页面并不代表示例一定正确。继续执行文档测试:

bash
cargo test --doc

预期输出:

text
   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 一致

下一课预告

下一课将继续整理测试与文档工作流,把文档生成和文档测试接入日常开发检查。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

生成项目文档

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通