From c2ac77453ad12a50d09c61abf14579eb3d4048d4 Mon Sep 17 00:00:00 2001 From: Taylor Yu Date: Sun, 3 May 2026 22:39:25 -0500 Subject: [PATCH 1/3] add xtask doctest Add a new `xtask`` command `doctest` that runs `mdbook test`. This ensures that `rustdoc`, when run from `mdbook`, will use the toolchain override. fixes #2251 --- tools/xtask/src/main.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/xtask/src/main.rs b/tools/xtask/src/main.rs index b790fea171..294495319f 100644 --- a/tools/xtask/src/main.rs +++ b/tools/xtask/src/main.rs @@ -18,6 +18,7 @@ fn main() -> Result<()> { cargo_test()?; eprintln!("all tests passed!"); } + Some("doctest") => mdbook_test()?, Some("linkcheck") => linkcheck(args)?, Some("style-check") => style_check()?, Some("-h" | "--help") => eprintln!("valid options: {OPTIONS}"), From ad8504aaeb9fcdcb334593e9acc00196da9df55e Mon Sep 17 00:00:00 2001 From: Taylor Yu Date: Mon, 4 May 2026 14:07:22 -0500 Subject: [PATCH 2/3] adjust dev-guide for xtask doctest --- dev-guide/src/tests.md | 6 ++++-- dev-guide/src/tooling/building.md | 1 - 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/dev-guide/src/tests.md b/dev-guide/src/tests.md index 9bb2c462bf..3d33a5e305 100644 --- a/dev-guide/src/tests.md +++ b/dev-guide/src/tests.md @@ -3,7 +3,7 @@ There are several different kinds of tests you can run (these are enforced in CI): - [`cargo xtask test-all`](#all-tests) --- Runs all tests. -- [`mdbook test`](#inline-tests) --- Tests the inline Rust code blocks. +- [`cargo xtask doctest`](#inline-tests) --- Tests the inline Rust code blocks. - [`cargo xtask linkcheck`](#linkcheck) --- Validates that Markdown links aren't broken. - [`cargo xtask style-check`](#style-checks) --- Validates various style checks. - [Code formatting](#code-formatting) --- Checks that all Rust tooling code is formatted. @@ -22,11 +22,13 @@ We recommend running this as a last step before opening a PR. This runs most of ## Inline tests ```sh -mdbook test +cargo xtask doctest ``` This command runs all tests that are inline in the Markdown. Internally, this uses [`rustdoc`](https://doc.rust-lang.org/rustdoc/) to run the tests and supports all the same features. Any code block with the `rust` language will be compiled unless it is ignored. See [Examples] for more. +Previous versions of this guide suggested `mdbook test`, but this only works reliably if your default toolchain is nightly. + ## Linkcheck ```sh diff --git a/dev-guide/src/tooling/building.md b/dev-guide/src/tooling/building.md index 0c34ad60e4..8571a58c5f 100644 --- a/dev-guide/src/tooling/building.md +++ b/dev-guide/src/tooling/building.md @@ -17,7 +17,6 @@ First, ensure that you have a recent copy of the nightly Rust compiler installed ```sh rustup toolchain install nightly -rustup override set nightly ``` Now, ensure you have `mdbook` installed, as this is needed to build the Reference: From ffe4cfdbc88f1b3bf45ddb118d66b673b3434a44 Mon Sep 17 00:00:00 2001 From: Taylor Yu Date: Mon, 4 May 2026 14:22:38 -0500 Subject: [PATCH 3/3] update for review comments Rename the xtask command to `mdbook-test`. Adjust documentation accordingly. Adjust `OPTIONS`` in xtask. --- dev-guide/src/examples.md | 4 ++-- dev-guide/src/tests.md | 4 ++-- tools/xtask/src/main.rs | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/dev-guide/src/examples.md b/dev-guide/src/examples.md index 714ce115ce..4dd6888f78 100644 --- a/dev-guide/src/examples.md +++ b/dev-guide/src/examples.md @@ -29,9 +29,9 @@ When demonstrating success cases, multiple cases may be included in a single cod ## Testing examples -The Rust code blocks are tested in CI. You can verify that the samples pass by running [`mdbook test`]. +The Rust code blocks are tested in CI. You can verify that the samples pass by running [`cargo xtask mdbook-test`]. -[`mdbook test`]: tests.md#inline-tests +[`cargo xtask mdbook-test`]: tests.md#inline-tests [mdBook supported languages]: https://rust-lang.github.io/mdBook/format/theme/syntax-highlighting.html#supported-languages [rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html [tested via rustdoc]: tests.md#inline-tests diff --git a/dev-guide/src/tests.md b/dev-guide/src/tests.md index 3d33a5e305..cffdbdc03a 100644 --- a/dev-guide/src/tests.md +++ b/dev-guide/src/tests.md @@ -3,7 +3,7 @@ There are several different kinds of tests you can run (these are enforced in CI): - [`cargo xtask test-all`](#all-tests) --- Runs all tests. -- [`cargo xtask doctest`](#inline-tests) --- Tests the inline Rust code blocks. +- [`cargo xtask mdbook-test`](#inline-tests) --- Tests the inline Rust code blocks. - [`cargo xtask linkcheck`](#linkcheck) --- Validates that Markdown links aren't broken. - [`cargo xtask style-check`](#style-checks) --- Validates various style checks. - [Code formatting](#code-formatting) --- Checks that all Rust tooling code is formatted. @@ -22,7 +22,7 @@ We recommend running this as a last step before opening a PR. This runs most of ## Inline tests ```sh -cargo xtask doctest +cargo xtask mdbook-test ``` This command runs all tests that are inline in the Markdown. Internally, this uses [`rustdoc`](https://doc.rust-lang.org/rustdoc/) to run the tests and supports all the same features. Any code block with the `rust` language will be compiled unless it is ignored. See [Examples] for more. diff --git a/tools/xtask/src/main.rs b/tools/xtask/src/main.rs index 294495319f..5d4b3b65cf 100644 --- a/tools/xtask/src/main.rs +++ b/tools/xtask/src/main.rs @@ -8,7 +8,7 @@ type Result = std::result::Result>; fn main() -> Result<()> { let mut args = std::env::args().skip(1); let cmd = args.next(); - const OPTIONS: &str = "linkcheck, style-check, test-all"; + const OPTIONS: &str = "mdbook-test, linkcheck, style-check, test-all"; match cmd.as_deref() { Some("test-all") => { mdbook_test()?; @@ -18,7 +18,7 @@ fn main() -> Result<()> { cargo_test()?; eprintln!("all tests passed!"); } - Some("doctest") => mdbook_test()?, + Some("mdbook-test") => mdbook_test()?, Some("linkcheck") => linkcheck(args)?, Some("style-check") => style_check()?, Some("-h" | "--help") => eprintln!("valid options: {OPTIONS}"),