Extern crate

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)
 

Cargo.toml

@@ -1,13 +1,25 @@
 [workspace]
-members = [".", "examples/remove-emphasis/mdbook-remove-emphasis"]
+members = [".", "examples/remove-emphasis/mdbook-remove-emphasis", "guide"]
+
+[workspace.dependencies]
+anyhow = "1.0.71"
+clap = { version = "4.3.12", features = ["cargo", "wrap_help"] }
+mdbook = { path = "." }
+pulldown-cmark = { version = "0.10.0", default-features = false, features = [
+    "html",
+] } # Do not update, part of the public api.
+serde = { version = "1.0.163", features = ["derive"] }
+serde_json = "1.0.96"
+semver = "1.0.17"
+
 
 [package]
 name = "mdbook"
 version = "0.4.43"
 authors = [
     "Mathieu David <[email protected]>",
     "Michael-F-Bryan <[email protected]>",
-    "Matt Ickstadt <[email protected]>"
+    "Matt Ickstadt <[email protected]>",
 ]
 documentation = "https://rust-lang.github.io/mdBook/index.html"
 edition = "2021"
@@ -20,23 +32,24 @@ description = "Creates a book from markdown files"
 rust-version = "1.74"
 
 [dependencies]
-anyhow = "1.0.71"
+anyhow.workspace = true
 chrono = { version = "0.4.24", default-features = false, features = ["clock"] }
-clap = { version = "4.3.12", features = ["cargo", "wrap_help"] }
+clap.workspace = true
 clap_complete = "4.3.2"
+cargo-manifest = "0.17.0"
 once_cell = "1.17.1"
 env_logger = "0.11.1"
 handlebars = "6.0"
 log = "0.4.17"
 memchr = "2.5.0"
 opener = "0.7.0"
-pulldown-cmark = { version = "0.10.0", default-features = false, features = ["html"] } # Do not update, part of the public api.
+pulldown-cmark.workspace = true
 regex = "1.8.1"
-serde = { version = "1.0.163", features = ["derive"] }
-serde_json = "1.0.96"
+serde.workspace = true
+serde_json.workspace = true
 shlex = "1.3.0"
 tempfile = "3.4.0"
-toml = "0.5.11" # Do not update, see https://github.com/rust-lang/mdBook/issues/2037
+toml = "0.5.11"                                                                 # Do not update, see https://github.com/rust-lang/mdBook/issues/2037
 topological-sort = "0.2.2"
 
 # Watch feature
@@ -59,7 +72,7 @@ ammonia = { version = "4.0.0", optional = true }
 assert_cmd = "2.0.11"
 predicates = "3.0.3"
 select = "0.6.0"
-semver = "1.0.17"
+semver.workspace = true
 pretty_assertions = "1.3.0"
 walkdir = "2.3.3"
 

guide/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "mdbook-book-code-samples"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+anyhow.workspace = true
+clap.workspace = true
+mdbook.workspace = true
+pulldown-cmark.workspace = true
+pulldown-cmark-to-cmark = "18.0.0"
+serde.workspace = true
+serde_json.workspace = true
+semver.workspace = true

guide/book.toml

@@ -5,7 +5,8 @@ authors = ["Mathieu David", "Michael-F-Bryan"]
 language = "en"
 
 [rust]
-edition = "2018"
+## not needed, and will cause an error, if using Cargo.toml: edition = "2021"
+manifest = "Cargo.toml"
 
 [output.html]
 smart-punctuation = true

guide/src/cli/test.md

@@ -1,32 +1,16 @@
 # The test command
 
-When writing a book, you sometimes need to automate some tests. For example,
+When writing a book, you may want to provide some code samples,
+and it's important that these be kept accurate as your software API evolves.
+For example,
 [The Rust Programming Book](https://doc.rust-lang.org/stable/book/) uses a lot
-of code examples that could get outdated. Therefore it is very important for
-them to be able to automatically test these code examples.
+of code samples that could become outdated as the language evolves.
 
-mdBook supports a `test` command that will run all available tests in a book. At
-the moment, only Rust tests are supported.
+MdBook supports a `test` command which runs code samples in your book as doc tests to verify they
+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).
 
-#### Disable tests on a code block
-
-rustdoc doesn't test code blocks which contain the `ignore` attribute:
-
-    ```rust,ignore
-    fn main() {}
-    ```
-
-rustdoc also doesn't test code blocks which specify a language other than Rust:
-
-    ```markdown
-    **Foo**: _bar_
-    ```
-
-rustdoc *does* test code blocks which have no language specified:
-
-    ```
-    This is going to cause an error!
-    ```
+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
 
@@ -37,7 +21,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 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
@@ -53,15 +52,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/for_developers/backends.md

@@ -31,9 +31,9 @@ a [`RenderContext::from_json()`] constructor which will load a `RenderContext`.
 
 This is all the boilerplate necessary for our backend to load the book.
 
-```rust
+```rust,should_panic
+# // this sample panics because it can't open stdin
 // src/main.rs
-extern crate mdbook;
 
 use std::io;
 use mdbook::renderer::RenderContext;
@@ -55,14 +55,18 @@ fn main() {
 
 ## Inspecting the Book
 
-Now our backend has a copy of the book, lets count how many words are in each
+Now our backend has a copy of the book, let's count how many words are in each
 chapter!
 
 Because the `RenderContext` contains a [`Book`] field (`book`), and a `Book` has
 the [`Book::iter()`] method for iterating over all items in a `Book`, this step
 turns out to be just as easy as the first.
 
-```rust
+```rust,should_panic
+# // this sample panics because it can't open stdin
+use std::io;
+use mdbook::renderer::RenderContext;
+use mdbook::book::{BookItem, Chapter};
 
 fn main() {
     let mut stdin = io::stdin();
@@ -174,26 +178,25 @@ deserializing to some arbitrary type `T`.
 To implement this, we'll create our own serializable `WordcountConfig` struct
 which will encapsulate all configuration for this backend.
 
-First add `serde` and `serde_derive` to your `Cargo.toml`,
+First add `serde` to your `Cargo.toml`,
 
-```
-$ cargo add serde serde_derive
+```shell
+$ cargo add serde 
 ```
 
 And then you can create the config struct,
 
 ```rust
-extern crate serde;
-#[macro_use]
-extern crate serde_derive;
+use serde::{Serialize, Deserialize};
 
-...
+fn main() {
 
 #[derive(Debug, Default, Serialize, Deserialize)]
 #[serde(default, rename_all = "kebab-case")]
 pub struct WordcountConfig {
   pub ignores: Vec<String>,
 }
+}
 ```
 
 Now we just need to deserialize the `WordcountConfig` from our `RenderContext`