Cargo rdme

Cargo 命令，用于从您的包文档创建 README。

安装

您可以使用以下命令通过 cargo 安装 cargo rdme：cargo install cargo-rdme。

用法

Cargo rdme 会将您的包文档插入到 README 文件中。要控制文档插入的位置，您需要插入一个标记： <!-- cargo-rdme -->。例如，您可以在 README 文件开头添加一些华丽的徽章，然后跟随 rustdoc 文档。

[![Build Status](https://example.org/badge.svg)](https://example.org/link-to-ci)

<!-- cargo-rdme -->

运行 cargo rdme 后，您的 README 文件将类似于以下内容：

[![Build Status](https://example.org/badge.svg)](https://example.org/link-to-ci)

<!-- cargo-rdme start -->

<WHATEVER-YOUR-CRATES-DOC-IS>

<!-- cargo-rdme end -->

每次更改您的包文档时，只需运行 cargo rdme 以更新您的 README 文件。

自动转换

您的包文档并不总是直接映射到一个好的 README。例如，Rust 代码块可能有隐藏的行。这些不应该在 README 文件中显示。

本节介绍 cargo rdme 自动应用的转换，以生成更好的 README。

Rust 代码块

cargo rdme 以两种方式转换 Rust 代码块：

1. 以 # 开头的 Rust 代码块将被省略，就像在 rustdoc 中一样。
2. Rust 代码块被注解为 rust markdown 标签，以便获得适当的语法高亮。我们还移除了仅关注 rustdoc 的标签，例如 should_panic。

在下面的表中，您可以看到这些修改的示例。代码块现在被标记为 rust，并且隐藏的行已被删除。

//! To check if a number is prime do:
//!
//! ```
//! # fn main() {
//! for i in 2.. {
//!     if is_prime(i) {
//!         println!("{i}");
//!     }
//! }
//! # }
//! ```

To check if a number is prime do:

```rust
for i in 2.. {
    if is_prime(i) {
        println!("{i}");
    }
}
```

内部链接

Rust 的文档可以包含链接到包中定义的项目。这些链接在您的 README 文件中可能没有意义，因此 cargo rdme 自动生成链接到docs.rs 的内部链接。

目前我们仅支持以下形式的链接：[⋯](crate::⋯)，请确保使用该格式。对标准库的链接也得到支持，并且它们必须具有以下形式：[⋯](::<crate>::⋯)，其中 <crate> 是标准库的一部分的包，例如 std、core 或 alloc。引用样式链接也得到支持。

请查看下面的示例

//! To check if a number is prime use
//! [`is_prime`](crate::is_prime).

To check if a number is prime use
[`is_prime`](https://docs.rs/prime/latest/prime/fn.is_prime.html).

请注意，内部链接支持存在一些限制。这是一个复杂的特性：cargo rdme 需要执行一些工作才能创建到 docs.rs 的链接。这是因为链接包含了内部链接指向的项目类型，在 is_prime 的情况下，我们需要发现它是一个函数以生成以 fn.is_prime.html 结尾的链接。因此，内部链接支持应被视为“尽力而为”（例如，不要期望由宏生成的项能够被解析）。如果 cargo rdme 无法生成链接，它仍然会生成 README 文件，但会发出警告。

标题级别

默认情况下，包文档中的标题级别将在插入到 README 中的部分的级别下嵌套。可以通过 --heading-base-level 命令行标志或配置文件（见下例）更改此行为。

配置文件

如果 cargo rdme 的默认行为不适合您的项目，您可以在项目的根目录中创建一个配置文件 .cargo-rdme.toml。配置文件可以如下所示

# Override the README file path.  When this is not set cargo rdme will use the file path defined
# in the project’s `Cargo.toml`.
readme-path = "MY-README.md"

# What line terminator to use when generating the README file.  This can be "lf" or "crlf".
line-terminator = "lf"

# If you are using a workspace to hold multiple projects, use this to select the project from
# which to extract the documentation from.  It can be useful to also set `readme-path` to create
# the README file in the root of the project.
workspace-project = "subproject"

# Defines the base heading level to use when inserting the crate’s documentation in the
# README.  If this is not set the crate’s documentation will be inserted with its sections
# belonging to the README section where the insertion happens.
heading-base-level = 0

# The default entrypoint will be `src/lib.rs`.  You can change that in the `entrypoint` table.
[entrypoint]
# The entrypoint type can be "lib" or "bin".
type = "bin"
# When you set type to "bin" the entrypoint default to `src/main.rs`.  If you have binary targets
# specified in your cargo manifest you can select them by name with `bin-name`.
bin-name = "my-bin-name"

[intralinks]
# Defines the base url to use in intralinks urls.  The default value is `https://docs.rs`.
docs-rs-base-url = "https://mydocs.rs"
# Defines the version to use in intralinks urls.  The default value is `latest`.
docs-rs-version = "1.0.0"
# If this is set the intralinks will be stripping in the README file.
strip-links = false

这些设置可以通过命令行标志进行覆盖。运行 cargo rdme --help 获取更多信息。

与 CI 的集成

要验证您的 README 是否与包文档保持最新，您可以运行 cargo rdme --check。如果 README 是最新的，则退出代码将为 0，如果不最新，则为 3，如果有警告，则为 4。

如果您使用 GitHub Actions，可以将此步骤添加到验证 README 是否最新的步骤中

- name: Check if the README is up to date.
  run: |
    cargo install cargo-rdme
    cargo rdme --check