mdBook-Keeper

"Book-keeping for your testcases."

mdBook-keeper adds more testing features to mdBook, specifically support for third-party crates, and testing while compiling. My hope is that it will be merged into mdBook at some point in the future.

Current goals of this project include:

• Specifying third-party crates to include when testing a mdbook. (DONE)
• Running tests as part of the build, rather than as a seperate command. (DONE)
• Only running tests on code that has changed. (DONE)
• The ability to see compilation or build output as part of the book (both to aid in debugging, and possibly also as a permanent output). (TODO)

Installation

To install this tool, run:

$ cargo install mdbook-keeper

Then add it as a pre-processor. Add this snippet to the bottom of your book.toml

[preprocessor.keeper]
command = "mdbook-keeper"

Finally, build your book as normal:

$ mdbook build path/to/book

Using Crates From An Existing Project

Many use-cases of mdbook involve the documentation being a sub-folder of a project. To make it easy to support this use-case, you can simply tell mdbook-keeper which directory the Cargo.toml (and Cargo.lock, if present) exists in. To do this, add the following line after the [preprocessor.keeper] line in your book.toml:

# NOTE: the file Cargo.toml should exist at this path.
manifest_dir = "../../path/to/project/"

Because rustc does not read a Cargo.toml file, it requires that any crates you want to use be declared with either extern crate <name>; or its --extern option. To simplify things, if you always want to extern a crate, simply write the following under [preprocessor.keeper]. This will pass the --extern option to rustc.

externs = ["my_crate", "name_here"]

If you have built the existing project already, you may find it useful to get mdbook-keeper to use the same target directory as the project. This means that packages don't need to get re-built in two different locations when building the book and the project. Add the following line after the [preprocessor.keeper] line in your book.toml:

# NOTE: the `debug` folder should exist at this path.
target_dir = "../../path/to/target/"

Using Extra Crates When In A Stand-Alone Book

If you don't have an existing project, the current solution is to create a minimal project inside the book repo. The project need only contain Cargo.toml, Cargo.lock, and src/main.rs (or src/lib.rs). Place all required dependencies in the Cargo.toml.

Then, point manifest_dir to that directory, as shown above.

Working with cargo workspaces and build features

If you are working with a cargo workspace, you'll need to have the --workspace argument passed to the invocation of cargo build. Likewise, if you need to build your crate with specific features enabled, you'll need to pass them via --features first,second - as a comma separated list. In the mdbook-keeper config, you can do so via:

is_workspace = true
build_features = ["first", "second"]

Both of these are optional: if they are not present in the config, the manifest dir is not considered a workspace and no features get enabled.

Other Configuration Options

All of these options can be placed in the book.toml file, after [preprocessor.keeper].

• test_dir this directory is where all intermediate work is stored, including a target/ folder if one is not specified. If you don't like the default location (./doctest_cache/), you can change it here.
• terminal_colors sets whether to show ANSI terminal colours in rustc output. It defaults to true only if you are on a TTY, and false otherwise.

Note on differences to DocTest

mdbook-keeper is not a perfect replacement to doctest. This is for a few reasons:

• Because much of the code is based on rust-skeptic, we use their rules for parsing markdown files. See their project for a detailed list of rules, but in short; we don't automatically insert a main() function for you, and you must tag codeblocks as rust to have them run.

• The output format is different, mainly because replicating doctest seemed unnecessary, complex, and brittle.

• This runs on mdbook build, rather than as a seperate command.

Thanks to Skeptic

Some of the code in this project was taken from the rust-skeptic project. Indeed, this project was briefly named mdbook-skeptic to acknowledge the code they wrote which was incredibly useful in writing this crate.

License

All the code in this repository is released under the APACHE-2.0 or MIT licenses.