Doc changes to cover how to use external crates in doctests (and relation to rustdoc)

Author: bobhy

guide/src/SUMMARY.md

@@ -7,7 +7,6 @@
 - [Installation](guide/installation.md)
 - [Reading Books](guide/reading.md)
 - [Creating a Book](guide/creating.md)
-- [Writing Code Samples](guide/writing.md)
 
 # Reference Guide
 

guide/src/cli/test.md

@@ -8,9 +8,7 @@ of code samples that could get outdated as the language evolves. Therefore it is
 them to be able to automatically test these code examples.
 
 mdBook supports a `test` command that will run code samples as doc tests for your book. At
-the moment, only Rust doc tests are supported.  
-
-For details on writing code samples and runnable code samples in your book, see [Writing](../guide/writing.md).
+the moment, only Rust doc tests are supported.
 
 #### Specify a directory
 
@@ -21,10 +19,22 @@ instead of the current working directory.
 mdbook test path/to/book
 ```
 
-#### `--library-path`
+#### `--dest-dir`
+
+The `--dest-dir` (`-d`) option allows you to change the output directory for the
+book. Relative paths are interpreted relative to the book's root directory. If
+not specified it will default to the value of the `build.build-dir` key in
+`book.toml`, or to `./book`.
+
+#### `--chapter`
+
+The `--chapter` (`-c`) option allows you to test a specific chapter of the
+book using the chapter name or the relative path to the chapter.
+
+#### `--library-path` `[`deprecated`]`
 
-> Note: This argument doesn't provide sufficient information for current Rust compilers.  
-Instead, add `package-dir` to your ***book.toml***, as described in [configuration](/format/configuration/general.md#rust-options).
+> Note: This argument doesn't provide sufficient extern crate information to run doc tests in current Rust compilers.  
+Instead, add **manifest** to point to a **Cargo.toml** 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
@@ -41,15 +51,3 @@ mdbook test my-book -L target/debug/deps/
 
 See the `rustdoc` command-line [documentation](https://doc.rust-lang.org/rustdoc/command-line-arguments.html#-l--library-path-where-to-look-for-dependencies)
 for more information.
-
-#### `--dest-dir`
-
-The `--dest-dir` (`-d`) option allows you to change the output directory for the
-book. Relative paths are interpreted relative to the book's root directory. If
-not specified it will default to the value of the `build.build-dir` key in
-`book.toml`, or to `./book`.
-
-#### `--chapter`
-
-The `--chapter` (`-c`) option allows you to test a specific chapter of the
-book using the chapter name or the relative path to the chapter.

guide/src/format/configuration/general.md

@@ -11,7 +11,7 @@ authors = ["John Doe"]
 description = "The example book covers examples."
 
 [rust]
-edition = "2018"
+manifest = "./Cargo.toml"
 
 [build]
 build-dir = "my-example-book"
@@ -30,14 +30,24 @@ limit-results = 15
 
 ## Supported configuration options
 
-It is important to note that **any** relative path specified in the
+> Note: **any** relative path specified in the
 configuration will always be taken relative from the root of the book where the
 configuration file is located.
 
 ### General metadata
 
 This is general information about your book.
 
+```toml
+[book]
+title = "Example book"
+authors = ["John Doe", "Jane Doe"]
+description = "The example book covers examples."
+src = "my-src"  # source files in `root/my-src` instead of `root/src`
+language = "en"
+text-direction = "ltr"
+```
+
 - **title:** The title of the book
 - **authors:** The author(s) of the book
 - **description:** A description for the book, which is added as meta
@@ -50,44 +60,25 @@ This is general information about your book.
 - **text-direction**: The direction of text in the book: Left-to-right (LTR) or Right-to-left (RTL). Possible values: `ltr`, `rtl`.
   When not specified, the text direction is derived from the book's `language` attribute.
 
-**book.toml**
-```toml
-[book]
-title = "Example book"
-authors = ["John Doe", "Jane Doe"]
-description = "The example book covers examples."
-src = "my-src"  # the source files will be found in `root/my-src` instead of `root/src`
-language = "en"
-text-direction = "ltr"
-```
-
 ### Rust options
 
 Options for the Rust language, relevant to running tests and playground
 integration.
 
 ```toml
 [rust]
-package-dir = "folder/for/Cargo.toml"
-edition = "2015"   # the default edition for code blocks
+manifest = "path/for/Cargo.toml"
+edition = "2015"   # [deprecated] the default edition for code blocks
 ```
 
-- **package-dir**: Folder containing a Cargo package whose targets and dependencies 
-you want to use in your book's code samples.  
-It must be specified if you want to test code samples with `use` statements, even if
-there is a `Cargo.toml` in the folder containing the `book.toml`. 
-This can be a relative path, relative to the folder containing `book.toml`.
-
-- **edition**: Rust edition to use by default for the code snippets. Default
-  is `"2015"`. Individual code blocks can be controlled with the `edition2015`,
-  `edition2018` or `edition2021` annotations, such as:
-
-  ~~~text
-  ```rust,edition2015
-  // This only works in 2015.
-  let try = true;
-  ```
-  ~~~
+- **manifest**: Path to a ***Cargo.toml*** file which is used to resolve dependencies of your sample code.  mdBook also uses the `package.edition` configured in the cargo project as the default for code snippets in your book.  
+See [Using External Crates and Dependencies](/format/mdbook.html#using-external-crates-and-dependencies) for details.
+
+- **edition** `[`deprecated`]`: Rust edition to use by default for the code snippets.  
+Default is `"2015"`. Individual code blocks can be controlled with the `edition2015`,
+  `edition2018` or `edition2021` annotations, as described in [Rust code block attributes](/format/mdbook.html#rust-code-block-attributes).  
+  This option is deprecated because it's only useful if your code samples don't depend on external crates or you're not doctest'ing them.  In any case, this option cannot be specified if **manifest** is configured.
+
 
 
 ### Build options

guide/src/format/mdbook.md

@@ -1,5 +1,9 @@
 # mdBook-specific features
 
+# Features for 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.
+
 ## Hiding code lines
 
 There is a feature in mdBook that lets you hide code lines by prepending them with a specific prefix.
@@ -306,6 +310,21 @@ And the `editable` attribute will enable the [editor] as described at [Rust code
 
 [Rust Playground]: https://play.rust-lang.org/
 
+## Using external crates and dependencies
+
+If your code samples depend on external crates, you will probably want to include `use <crate>` statements in the code and want them to resolve and allow documentation tests to run.
+To configure this:
+
+1. Create a ***Cargo.toml*** file with a `[package.dependencies]` section that defines a dependency for each `<crate>` you want to use in any sample.  If your book is already embedded in an existing Cargo project, you may be able to use the existing project `Cargo.toml`.
+2. In your ***book.toml***:
+    * configure the path to ***Cargo.toml** in `rust.manifest`, as described in [rust configuration](/format/configuration/general.html#rust-options).
+    * remove `rust.edition` if it is configured.  The edition of rust compiler will be as specified in the ***Cargo.toml***.
+    * Refrain from invoking `mdbook test` with `-L` or `--library-path` argument.  This, too, will be inferred from cargo project configuration
+
+# Features for general content
+
+These can be used in markdown text (outside code blocks).
+
 ## Controlling page \<title\>
 
 A chapter can set a \<title\> that is different from its entry in the table of

guide/src/guide/writing.md

@@ -67,7 +67,8 @@ impl ExternArgs {
         let proj_root = cargo_path
             .canonicalize()?
             .parent()
-            .ok_or(anyhow!("can't find parent of {:?}", cargo_path))?.to_owned();
+            .ok_or(anyhow!("can't find parent of {:?}", cargo_path))?
+            .to_owned();
         let mut manifest = Manifest::from_path(&cargo_path)?;
         manifest.complete_from_path(&proj_root)?; // try real hard to determine bin or lib
         let package = manifest