用法

首先，将以下内容添加到您的 Cargo.toml

[dev-dependencies]
readme-sync = "0.2.1"

然后添加一个集成测试，使用必要的 README 和文档修饰符，并使用 assert_sync 函数检查它们的同步。

以下示例用于测试此 crate 的 README 和文档的同步。您可以复制它并遵循诊断消息来调整使用的修饰符，并更正您的 README 和文档。

#[cfg(test)]
#[test]
fn readme_sync_test() {
    use readme_sync::{assert_sync, CMarkDocs, CMarkReadme, Config, Package};
    use std::borrow::ToOwned;

    let package = Package::from_path(env!("CARGO_MANIFEST_DIR").into()).unwrap();
    let config = Config::from_package_docs_rs_features(&package);
    let readme = CMarkReadme::from_package(&package).unwrap();
    let docs = CMarkDocs::from_package_and_config(&package, &config).unwrap();

    let readme = readme
        .remove_badges_paragraph()
        .remove_documentation_section()
        .remove_codeblock_tag("no_sync")
        .disallow_absolute_repository_blob_links()
        .unwrap()
        .use_absolute_repository_blob_urls()
        .unwrap();

    let docs = docs
        .increment_heading_levels()
        .add_package_title()
        .remove_codeblock_rust_test_tags()
        .use_default_codeblock_rust_tag()
        .remove_hidden_rust_code()
        .map_links(
            |link| match link {
                "CMarkDocs::map_links" => "struct.CMarkDocs.html#method.map_links".into(),
                link => link.into(),
            },
            "workaround for intra-doc links",
        )
        .disallow_absolute_package_docs_links()
        .unwrap()
        .use_absolute_package_docs_urls()
        .unwrap();

    assert_sync(&readme, &docs);
}

请注意，cargo build 和 cargo test 都会启用 dev-dependencies 的功能，所以如果您想在没有这些功能的情况下测试您的 crate（例如在 no_std 环境中），您可以使用 readme-sync 并指定 default-features = false。有关更多详细信息，请参阅本常见问题解答部分。

文档

API 文档

功能标志

• codemap（默认启用）：启用 codemap 依赖项，这对于 assert_sync 和其他诊断功能是必需的。
• codemap-diagnostic（默认启用）：启用 codemap-diagnostic 依赖项，这对于 assert_sync 和其他诊断功能是必需的。
• glob（默认启用）：启用 gloc 依赖项，这对于徽章检测和类似 CMarkReadme::remove_badges_paragraph 的方法是必需的。
• platforms：启用 platforms 依赖项和方法 Config::with_target_arch_os_env。
• proc-macro2（默认启用）：启用 proc-macro2 依赖项，并启用 span-locations 功能，这使得 crate 能够显示源 Rust 文件的错误位置。
• pulldown-cmark（默认启用）：启用 pulldown-cmark 依赖项，对于几乎所有的东西都是必需的，除了清单和文档解析以及一些实用函数。
• serde（默认启用）：启用 serde 依赖项，对于清单反序列化是必需的。
• syn（默认启用）：启用 syn 依赖项，对于文档解析是必需的。
• thiserror（默认启用）：启用 thiserror 依赖项，对于所有可能返回错误的函数和方法是必需的。
• toml（默认启用）：启用 toml 依赖项，对于清单解析是必需的。

其他 crate

• cargo-sync-readme：从文档生成 readme 部分。它不支持 doc-attributes，也不提供差异的诊断。但如果您只需要同步 readme 和文档文本或检查它们是否同步，这可能是一个更好的选择。
• version-sync：crate 可以轻松添加一个集成测试，检查当 crate 版本更改时 README.md 和文档是否已更新。

常见问题解答

是否支持 Rust 内部文档链接？

目前不支持内部文档链接解析。可以使用 CMarkDocs::map_links 更改文档中的结构引用。Pulldown cmark 也需要指定链接地址。

为什么示例集成测试如此之长，而且没有一次性完成所有工作的函数？

readme 和文档的转换在不同 crate 之间差异很大，而这个 crate 的 API 尚未稳定。

然而，目前它支持广泛的定制。您可以指定 readme 和 docs 的路径、它们的 内容、使用的功能和转换，以及使用您自己的转换。

因此，任何反馈都受欢迎！

为什么使用 syn 而不是仅仅解析文档注释？

由于 cfg 和 cfg_attr 有助于文档测试，这些测试需要一些特定功能，并且只能与这些功能一起编译。

为什么使用 Markdown 而不是文本比较呢？

它简化了 Markdown 转换。转换是必要的，因为说明文件内容和文档首页之间存在一些差异，包括：crate 名称的存在、不同的标题级别、徽章的存在、不同的相对 URL 根等。

为什么所有依赖都是可选的？

默认情况下，Rust 编译器为 cargo test 和 cargo build 等命令启用 dev-dependencies 的功能。因此，dev-dependencies 使用的功能在测试期间隐式启用。由于所有 readme-sync 依赖都是可选的，您可以在测试时轻松保护您的 crate，防止隐式启用公共功能。

有关更多详细信息，请参阅 rust-lang/cargo#7916。

如何防止为我的 crate 的依赖项启用 readme-sync 依赖项的功能。

如果您使用的是 nightly Rust，您可以使用 -Z features=dev_dep 标志。

或者，在任何 Rust 版本中，您可以使用以下方式禁用所有 readme-sync 依赖项：

[dev-dependencies.readme-sync]
version = "0.2.1"
default-features = false

这将帮助您避免从 dev-dependencies 中注入功能。

在这种情况下，为了使用 readme-sync 功能，您需要添加一个功能，该功能重新启用 readme-sync 默认功能，并可用于运行 readme 同步集成测试。

[features]
test-readme-sync = ["readme-sync/default"]

然后您需要将 test-readme-sync 条件检查添加到您的 readme 同步集成测试中。

#[cfg(all(test, feature = "test-readme-sync"))]
//    ^^^^    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#[test]
fn readme_sync_test() {
    // ...
}

并运行它：

cargo test --features "test-readme-sync"

许可证

根据您选择的以下许可证之一授权：

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

任选其一。

贡献

除非您明确声明，否则您根据 Apache-2.0 许可证定义的任何贡献，均应按上述方式双重许可，而无需任何附加条款或条件。