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 9bb2c462bf..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. -- [`mdbook test`](#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,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 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. +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: diff --git a/tools/xtask/src/main.rs b/tools/xtask/src/main.rs index b790fea171..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,6 +18,7 @@ fn main() -> Result<()> { cargo_test()?; eprintln!("all tests passed!"); } + Some("mdbook-test") => mdbook_test()?, Some("linkcheck") => linkcheck(args)?, Some("style-check") => style_check()?, Some("-h" | "--help") => eprintln!("valid options: {OPTIONS}"),