finalize doc updates for new feature

Author: bobhy

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## mdBook 0.4.43+ (tba)
+
+### Fixed
+
+- Allow doctests to use external crates by referencing a `Cargo.toml`
+
 ## mdBook 0.4.43
 [v0.4.42...v0.4.43](https://github.com/rust-lang/mdBook/compare/v0.4.42...v0.4.43)
 

guide/src/cli/test.md

@@ -7,7 +7,9 @@ For example,
 of code samples that could become outdated as the language evolves.
 
 MdBook supports a `test` command which runs code samples in your book as doc tests to verify they
-will compile, and, optionally, run correctly. 
+will compile, and, optionally, run correctly.
+For details on how to specify the test to be done and outcome to be expected, see [Code Blocks](/format/mdbook.md#code-blocks).
+
 At the moment, mdBook only supports doc *tests* written in Rust, although code samples can be written and *displayed* in many programming languages.
 
 #### Specify a directory
@@ -36,7 +38,6 @@ book using the chapter name or the relative path to the chapter.
 ***Note*** This argument is deprecated.  Since Rust edition 2018, the compiler needs an explicit `--extern` argument for each external crate used in a  doc test, it no longer simply scans the library path for likely-looking crates.  
 New projects should list external crates as dependencies in a **Cargo.toml** file and reference that file in your ***book.toml***, as described in [rust configuration](/format/configuration/general.html#rust-options).
 
-
 The `--library-path` (`-L`) option allows you to add directories to the library
 search path used by `rustdoc` when it builds and tests the examples. Multiple
 directories can be specified with multiple options (`-L foo -L bar`) or with a

guide/src/format/mdbook.md

@@ -1,8 +1,8 @@
 # mdBook-specific features
 
-# Features for code blocks
+# Code blocks
 
-These capabilities primarily affect how the user sees or interacts with code samples in your book and are supported directly by mdBook.  Some also affect documentation tests (for which mdBook invokes `rustdoc --test`): this is detailed in the sections below.
+These capabilities primarily affect how the user sees or interacts with code samples in your book and are supported directly by mdBook.  Some also affect running the sample as a documentation test. (for which mdBook invokes `rustdoc --test`), so : this is detailed in the sections below.
 
 ## Hiding code lines
 
@@ -12,7 +12,7 @@ For the Rust language, you can use the `#` character as a prefix which will hide
 
 [rustdoc-hide]: https://doc.rust-lang.org/stable/rustdoc/write-documentation/documentation-tests.html#hiding-portions-of-the-example
 
-```bash
+```text
 # fn main() {
     let x = 5;
     let y = 6;
@@ -44,7 +44,7 @@ python = "~"
 
 The prefix will hide any lines that begin with the given prefix. With the python prefix shown above, this:
 
-```bash
+```text
 ~hidden()
 nothidden():
 ~    hidden()
@@ -155,6 +155,7 @@ interpreting them.
 ````
 
 ## Including portions of a file
+
 Often you only need a specific part of the file, e.g. relevant lines for an
 example. We support four different modes of partial includes:
 
@@ -179,6 +180,7 @@ the regex `ANCHOR_END:\s*[\w_-]+`. This allows you to put anchors in
 any kind of commented line.
 
 Consider the following file to include:
+
 ```rs
 /* ANCHOR: all */
 
@@ -196,6 +198,7 @@ impl System for MySystem { ... }
 ```
 
 Then in the book, all you have to do is:
+
 ````hbs
 Here is a component:
 ```rust,no_run,noplayground

guide/src/guide/README.md

@@ -4,5 +4,4 @@ This user guide provides an introduction to basic concepts of using mdBook.
 
 - [Installation](installation.md)
 - [Reading Books](reading.md)
-- [Creating a Book](creating.md)
-- [Writing Code Samples](writing.md)
+- [Creating a Book](creating.md)q