add xtask doctest

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

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

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:

tools/xtask/src/main.rs

@@ -8,7 +8,7 @@ type Result<T> = std::result::Result<T, Box<dyn Error>>;
 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}"),