13 unstable releases (4 breaking)
0.5.0 | Feb 11, 2024 |
---|---|
0.4.0 | Jan 19, 2024 |
0.3.1 | Jul 24, 2023 |
0.3.0 | Jun 7, 2023 |
0.1.3 | Oct 17, 2022 |
#427 in Text processing
120 downloads per month
45KB
955 lines
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 atarget/
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 totrue
only if you are on a TTY, andfalse
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 amain()
function for you, and you must tag codeblocks asrust
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.
Dependencies
~16–32MB
~440K SLoC