cargo-readme

从文档注释中生成 README.md。

Cargo 子命令，从您的crate的文档注释中提取文档，可用于填充您的 README.md。

致谢

此库由 Livio Ribeiro (@livioribeiro) 编写，最初位于 https://github.com/livioribeiro/cargo-readme，现在重定向到这里（截至2023年8月）。感谢 Livio 为这个库做出的贡献！

安装

cargo install cargo-readme

动机

在编写文档时，您通常会展示如何使用您的软件的示例。但您如何确保所有示例都正常工作？在发生破坏性更改后，我们没有忘记更新它们，并且让我们的（可能新的）用户自己解决问题？

使用 cargo-readme，您只需编写 rustdoc，运行测试，然后运行

cargo readme > README.md

就是这样！您的 README.md 已填充了来自您的 lib.rs（或 main.rs）的文档注释内容。

用法

让我们看看以下 rust doc

//! This is my awesome crate
//!
//! Here goes some other description of what it is and what is does
//!
//! # Examples
//! ```
//! fn sum2(n1: i32, n2: i32) -> i32 {
//!   n1 + n2
//! }
//! # assert_eq!(4, sum2(2, 2));
//! ```

运行 cargo readme 将输出以下内容

[![Build Status](__badge_image__)](__badge_url__)

# my_crate

This is my awesome crate

Here goes some other description of what it is and what is does

## Examples
```rust
fn sum2(n1: i32, n2: i32) -> i32 {
  n1 + n2
}
```

License: MY_LICENSE

让我们看看发生了什么

• 创建了一个来自 [badges] 部分的徽章
• 添加了crate名称 ("my-crate")
• "# Examples" 标题变为 "## Examples"
• 代码块变更为 "```rust"
• 隐藏的行 # assert_eq!(4, sum2(2, 2)); 已被移除

cargo-readme 也支持多行文档注释 /*! */（但您不能混合样式）

/*!
This is my awesome crate

Here goes some other description of what it is and what is does

```
fn sum2(n1: i32, n2: i32) -> i32 {
  n1 + n2
}
```
*/

如果您有不适合文档注释的额外信息，可以使用模板。只需在 Cargo.toml 所在目录下创建一个名为 README.tpl 的文件，并包含以下内容

{{badges}}

# {{crate}}

{{readme}}

Current version: {{version}}

Some additional info here

License: {{license}}

输出将如下所示

[![Build Status](__badge_image__)](__badge_url__)

# my_crate

Current version: 3.0.0

This is my awesome crate

Here goes some other description of what it is and what is does

## Examples
```rust
fn sum2(n1: i32, n2: i32) -> i32 {
  n1 + n2
}
```

Some additional info here

License: MY_LICENSE

默认情况下，将使用 README.tpl 作为模板，但您可以使用 --template 覆盖它以选择不同的模板，或者使用 --no-template 禁用它。

许可证

许可方式为以下之一

• Apache License，版本 2.0，(LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 https://opensource.org/licenses/MIT)

由您选择。

贡献

除非您明确声明，否则您提交给作品以供包含在内的任何贡献，根据 Apache-2.0 许可证的定义，将按上述方式双许可，不附加任何额外条款或条件。