## bin+lib mdbook-keeper

An improved testing experience for mdbook

### 9 releases

 0.2.4 Feb 26, 2023 Feb 26, 2023 Jan 6, 2023 Oct 17, 2022

#445 in Text processing

MIT/Apache

41KB
878 lines

# mdBook-Keeper

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.

## 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.