Add a contributor tests chapter

Author: ehuss

contributor-guide/src/SUMMARY.md

@@ -6,7 +6,7 @@
 - [Reference tooling]()
     - [Building the Reference](tooling/building.md)
     - [mdbook-spec](tooling/mdbook-spec.md)
-- [Tests]()
+- [Tests](tests.md)
 - [Formatting](formatting/index.md)
     - [Markdown](formatting/markdown.md)
     - [Admonitions](formatting/admonitions.md)

contributor-guide/src/tests.md

@@ -0,0 +1,60 @@
+# Running tests
+
+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 codeblocks.
+- [`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.
+- [mdbook-spec tests](#mdbook-spec-tests) --- Internal tests for `mdbook-spec`.
+
+## All tests
+
+```sh
+cargo xtask test-all
+```
+
+This command runs all the tests listed below.
+
+We recommend running this as a last step before opening a PR. This runs most of the tests required for CI to pass. See [`xtask/src/main.rs`](https://github.com/rust-lang/reference/blob/master/xtask/src/main.rs) for details on what this does.
+
+## Inline tests
+
+```sh
+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 the [Examples chapter](examples.md) for more.
+
+## Linkcheck
+
+```sh
+cargo xtask linkcheck
+```
+
+This command verifies that links are not broken. It downloads and uses the [`linkchecker`](https://github.com/rust-lang/rust/tree/main/src/tools/linkchecker) script hosted in the `rust-lang/rust` repository.
+
+This requires a recent nightly installed via `rustup` and the `rust-docs` component.
+
+After compiling the script, it builds the Reference using `mdbook` and then scans all local links to verify that they are valid, particularly between various books. This does not check any network links.
+
+## Style checks
+
+```sh
+cargo xtask style-check
+```
+
+This uses the [`style-check`](https://github.com/rust-lang/reference/tree/master/style-check) tool to enforce various formatting rules.
+
+## Code formatting
+
+CI uses `cargo fmt --check` to verify that all Rust sources for the tools (like `mdbook-spec`) are properly formatted. All code must be formatted with `rustfmt`.
+
+## mdbook-spec tests
+
+```sh
+cargo test --manifest-path mdbook-spec/Cargo.toml
+```
+
+CI runs `cargo test` on `mdbook-spec` to execute any tests for the tool itself.

docs/authoring.md

@@ -4,14 +4,6 @@ This document serves as a guide for editors and reviewers. Some conventions and
 
 [introduction]: ../src/introduction.md
 
-### Linkcheck
-
-To verify that links are not broken, run `cargo xtask linkcheck`.
-
-### Running all tests
-
-As a last step before opening a PR, it is recommended to run `cargo xtask test-all`. This will go through and run most of the tests that are required for CI to pass. See `xtask/src/main.rs` for what all this does.
-
 ## Style
 
 Idioms and styling: