cargo-sync-rdme

Cargo 子命令，用于同步 README 与 cargo 清单和 crate 文档。

安装

安装 cargo-sync-rdme 有多种方法。选择以下最适合您需求的方法之一。

预构建的二进制文件

可执行二进制文件可在 GitHub 发布页面 下载。

使用 Rust 从源代码构建

要从源代码构建 cargo-sync-rdme 可执行文件，您必须安装 Rust 工具链。要安装 rust 工具链，请遵循 此指南。

安装 Rust 后，可以使用以下命令构建和安装 cargo-sync-rdme

# Install released version
$ cargo install cargo-sync-rdme

# Install latest version
$ cargo install --git https://github.com/gifnksm/cargo-sync-rdme.git cargo-sync-rdme

用法

cargo-sync-rdme 是一个子命令，用于同步 README.md 的内容与 cargo 清单和 crate 文档。通过在 README.md 中嵌入标记注释，您可以插入由 cargo-sync-rdme 生成的文档。以下有三类标记注释。

• <!-- cargo-sync-rdme title --> : 从包名称生成文档标题（H1 元素）。
• <!-- cargo-sync-rdme badge --> : 从包元数据生成徽章。
• <!-- cargo-sync-rdme rustdoc --> : 从文档注释生成 crate 的文档。

按照以下方式编写 README.md

<!-- cargo-sync-rdme title -->
<!-- cargo-sync-rdme badge -->
<!-- cargo-sync-rdme rustdoc -->

要更新 README.md 的内容，请运行以下命令

cargo sync-rdme --toolchain nightly

cargo-sync-rdme 使用了 rustdoc 的不稳定特性，因此需要 nightly 工具链来从 crate 文档中的注释生成 README。如果没有安装 nightly 工具链，可以使用以下命令进行安装：

rustup toolchain install nightly

README.md 的内容将更新如下：

<!-- cargo-sync-rdme title [[ -->
# (Package name)
<!-- cargo-sync-rdme ]] -->
<!-- cargo-sync-rdme badge [[ -->
(Badges)
<!-- cargo-sync-rdme ]] -->
<!-- cargo-sync-rdme rustdoc [[ -->
(Crate documentation)
<!-- cargo-sync-rdme ]] -->

请参阅 examples/lib 中的实际示例。

配置

您可以通过将以下部分添加到 Cargo.toml 来自定义 cargo-sync-rdme 的行为。

[package.metadata.cargo-sync-rdme.badges]
maintenance = true
license = true

[package.metadata.cargo-sync-rdme.rustdoc]
html-root-url = "https://gifnksm.github.io/cargo-sync-rdme/"

请参阅 配置 了解详细信息。

最低支持的 Rust 版本 (MSRV)

最低支持的 Rust 版本是 Rust 1.74.0。在任何时候都支持至少稳定 Rust 的最后 3 个版本。

当 crate 处于预发布状态（0.x.x）时，它可能在补丁版本中提高 MSRV。一旦 crate 达到 1.x，任何 MSRV 的提高都将伴随着一个新的次要版本。

许可证

本项目采用以下任一许可证：

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

供您选择。

贡献

除非您明确声明，否则根据 Apache-2.0 许可证定义的，任何有意提交给本项目并由您包含的工作的贡献，将根据上述方式双许可，不附加任何额外条款或条件。

请参阅 CONTRIBUTING.md。