什么是 rustdoc?

2023-10-02 11:33| 来源: 网络整理| 查看: 265

什么是 rustdoc？

中文翻译注（The Chinese translation of The rustdoc Book）：

👉 查看更多 Rust 官方文档中英文双语教程，包括双语版《Rust 程序设计语言》（出版书名为《Rust 权威指南》），本站还提供了 Rust 标准库中文版。《rustdoc 手册》（rustdoc Book 中文版）翻译自 rustdoc Book，内容已全部翻译完成，查看此书的 Github 翻译项目和源码。本文版最后更新时间：2022-02-04。本书主要译者：David，Rust 中文翻译项目组成员。本站支持文档中英文切换，点击页面右上角语言图标可切换到相同章节的英文页面，英文版每天都会自动同步一次官方的最新版本。若发现当前页表达错误或帮助我们改进翻译，可点击右上角的编辑按钮打开该页对应源码文件进行编辑和修改，Rust 中文资源的开源组织发展离不开大家，感谢您的支持和帮助！

标准 Rust 版本包含了名为 rustdoc 的工具。它的作用是为 Rust 项目生成文档，Rustdoc 接受一个 crate 根目录或者一个 markdown 文件作为参数，生成 HTML，CSS 和 JavaScript 文件。

基本使用

让我们试用一下，使用 Cargo 创建一个新项目

$ cargo new docs --lib $ cd docs

在 src/lib.rs 中，Cargo 生成了一些示例代码，将其删除并替换为下面的代码：

#![allow(unused)] fn main() { /// foo is a function fn foo() {} }

然后我们运行 rustdoc。我们可以在 crate 根路径执行下面的命令：

$ rustdoc src/lib.rs

这会创建一个新目录 doc，其中包含一个网站。在我们的例子中，主页面是 doc/lib/index.html。如果你使用浏览器打开，可以看到一个带有搜索栏的页面，在顶部可以看到“Crate lib”，页面没有内容。

配置 rustdoc

现在有两个问题：第一，为什么我们的包名字是“lib”？第二，为什么没有任何内容？

第一个问题的原因是因为 rustdoc 试图更好用，像 rustc 就假定我们 crate 的名字就是 crate 根目录文件的名字。为了修复这个问题，可以通过命令行传递参数：

$ rustdoc src/lib.rs --crate-name docs

现在，doc/docs/index.html 文件生成，页面名称为“Crate docs”。

对于第二个问题，因为我们的函数 foo 不是公共的；rustdoc 默认只会为公共函数生成文档，如果我们将代码修改为

#![allow(unused)] fn main() { /// foo is a function pub fn foo() {} }

然后重新运行 rustdoc：

$ rustdoc src/lib.rs --crate-name docs

现在我们生成了文档，打开 doc/docs/index.html，显示了 foo 函数的连接页面，文件位置是 doc/docs/fn.foo.html。在函数的页面上，你可以看到我们写的注释“foo is a function”。

通过 Cargo 使用 rustdoc

Cargo 整合了 rustdoc，使得生成文档更容易。代替 rustdoc 命令，我们可以这样做：

$ cargo doc

实际上，会这样调用 rustdoc:

$ rustdoc --crate-name docs src/lib.rs -o /docs/target/doc -L dependency=/docs/target/debug/deps

你可以使用 cargo doc --verbose 看到这个过程。

它会自动生成正确的 crate 名称 --crate-name，同时指向 src/lib.rs。但是其他的参数表示什么呢？

-o 控制文档的输出。不使用顶层的 doc 目录，Cargo 会把生成的文档生成在 target。这是 Cargo 项目的惯用生成文件的位置。 -L 帮助 rustdoc 找到代码的依赖，如果我们的项目有依赖，也会生成依赖的文档。 Outer 和 inner 文档

/// 语法用来对下面一个 item 生成文档，所以称为 outer 文档。还有语法//!，用来生成 item 内部的文档，也叫做 inner 文档，通常用来对整个 crate 生成文档，因为是 crate 的根，没有 item 在前面。所以为了生成整个 crate 的文档，你需要这样用 //!：

#![allow(unused)] fn main() { //! This is my first rust crate }

当这样用的时候，会生成 item 内部的文档，也就是 crate 自己。

为了获取更多 //! 的信息，请看 the Book

利用单独的 Markdown 文件

rustdoc 可以为单独的 markdown 文件生成 HTML。让我们尝试一下，创建 README.md，并输入如下内容：

# Docs This is a project to test out `rustdoc`. [Here is a link!](https://www.rust-lang.org) ## Example ```rust fn foo() -> i32 { 1 + 1 } ```

然后运行 rustdoc 命令：

$ rustdoc README.md

你能发现生成的 docs/doc/README.html 文件。

不过现在 Cargo 不能这样操作 markdown 文件。

总结

本节涵盖了 rustdoc 的基本使用方法。本书的剩余部分会展示 rustdoc 所有的可选功能，以及如何使用它们。

【本文地址】

什么是 rustdoc?

什么是 rustdoc?

今日新闻

推荐新闻