|0.2.4||Feb 26, 2023|
|0.2.3||Feb 26, 2023|
|0.2.0||Jan 6, 2023|
|0.1.3||Oct 17, 2022|
#445 in Text processing
96 downloads per month
"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)
To install this tool, run:
$ cargo install mdbook-keeper
Then add it as a pre-processor. Add this snippet to the bottom
[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.lock, if present)
exists in. To do this, add the following line after the
line in your
# NOTE: the file Cargo.toml should exist at this path. manifest_dir = "../../path/to/project/"
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
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
externs = ["my_crate", "name_here"]
If you have built the existing project already, you may find it useful to get
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
# 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
src/lib.rs). Place all required dependencies in the
manifest_dir to that directory, as shown above.
Other Configuration Options
All of these options can be placed in the
book.toml file, after
test_dirthis 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_colorssets whether to show ANSI terminal colours in rustc output. It defaults to
trueonly if you are on a TTY, and
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
rustto have them run.
- The output format is different, mainly because replicating
doctestseemed 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
Indeed, this project was briefly named
mdbook-skeptic to acknowledge the code they wrote
which was incredibly useful in writing this crate.
All the code in this repository is released under the APACHE-2.0 or MIT licenses.