5.1 文档

原文链接: https://rust-random.github.io/book/contrib-doc.html

风格

所有文档均为英文，但不偏好任何特定方言。

文档应面向多种受众：既包括经验丰富的 Rustacean，也包括相对新手；既有统计建模或密码学经验的人，也包括对这些主题陌生的人。由于往往无法编写适合所有人的文档，我们倾向于简洁的技术文档，并引用面向更特定受众的扩展文章。

API 文档

Rand crate

建议使用 nightly Rust 以获得正确的链接处理。

要为 rust-random/rand 仓库中所有 crate 构建全部 API 文档，运行：

1
2
3
4
5

# 可选，启用一些不稳定但广泛使用的文档特性：
export RUSTDOCFLAGS="--cfg docsrs -Zunstable-options --generate-link-to-definition"

# 为工作区中所有 crate 构建文档：
cargo doc --workspace --no-deps --all-features --open

（或者，查看 Cargo.toml 中的 [package.metadata.docs.rs]，其中可能包含工作区或 crate 特定的配置。）

在 Linux 上，可以轻松设置任何编辑后自动重建：

1

while inotifywait -r -e close_write src/ rand_*/; do cargo doc; done

编辑 API 文档后，我们建议测试示例：

1

cargo test --doc

Getrandom crate

rust-random/getrandom 仓库仅包含一个 crate，因此简单的 cargo doc 即可。

辅助文档

README 文件

README 文件包含 crate 的简要介绍、shield 徽章、有用链接、特性标志文档、许可信息，以及可能的示例。

大多数情况下，这些文件没有持续测试。包含示例的地方（目前仅 rand_jitter crate），我们通过 doc_comment 启用持续测试（参见 lib.rs:62 及之后）。

CHANGELOG 文件

变更日志格式基于 Keep a Changelog 格式。

自上次发布以来合并的所有重要更改应列在日志顶部的 [Unreleased] 部分下。

本书

本书的源码位于 rust-random/book 仓库。使用 mdbook 构建，使构建和测试变得简单：

1
2
3
4
5
6
7

cargo install mdbook --version "^0.4"

mdbook build --open
mdbook test

# 任何更改后自动重建：
mdbook watch

请注意，书中的链接是相对链接，设计为在已发布的书中工作。如果你在本地构建本书，你可能想设置一个指向你本地 API 文档构建的符号链接：

1

ln -s ../rand/target/doc rand