如何让Cargo执行README.md中的文档测试？以及解决README.md引入lib.rs时的语法警告问题

Alright, let's work through your issues step by step — I've run into these exact problems before, so I know how to fix them:

1. Fixing the README Import Syntax in lib.rs #

First, let's clear up the confusion around the doc attribute syntax:

• The old #[doc(include="../README.md")] syntax was indeed deprecated (as mentioned in that issue) because it didn't align with Rust's standard attribute patterns.
• The correct, stable replacement is #[doc = include_str!("../README.md")] — but that "unknown document attribute include_str" warning you're seeing? That's almost certainly because you're using an outdated Rust toolchain. This syntax was stabilized in Rust 1.54, so run rustup update to get the latest version, and that warning should disappear.

Double-check you're writing it exactly right: no extra parentheses around the include_str! call, just the attribute assigned directly to the macro output. That's key — any typos here will trigger weird warnings.

2. Running Documentation Tests from Your README #

Getting Cargo to test your README code examples is straightforward, but you need to set one thing up first:

Step 1: Update Cargo.toml #

Add a readme field to your [package] section so Cargo knows where to find your README:

[package]
name = "your-crate-name"
version = "0.1.0"
readme = "README.md"
# ... keep your other existing fields

Step 2: Run the Tests #

To run just the documentation tests (including those in your README), use:

cargo test --doc

If you want to run all tests (unit, integration, and docs) at once, just run cargo test like normal — it will automatically include your README's tests once you've set the readme field in Cargo.toml.

A quick reminder: Make sure your README's code examples use standard Rust doc test formatting (rust code blocks, optional `// comments to split test cases) so Cargo can recognize and run them properly.

内容的提问来源于stack exchange，提问作者Evan Carroll