Test Rust code blocks in your Markdown files.
This crate executes the code blocks in Markdown files by embedding them into
the Rust source and builds as a crate.
The advantage of this approach is that the dependency resolution are done by cargo
.
This means that that dependency problems associated with updating the Rust toolchain do not occur.
doubter
embeds the target Markdown files into the Rust code as the public doc comments.
Therefore, it is necessary to create a new crate for testing code blocks separately from the published crates.
This crate(s) are usually registered in [workspace.members]
.
Add the dependencies for doubter
to Cargo.toml
.
If some external crates are required in code blocks, specify them as the members of [dev-dependencies]
:
[dependencies]
doubter = "0.1.0"
[dev-dependencies]
rand = "0.5"
Then, modify src/lib.rs
to specify the path to target Markdown files.
#[macro_use]
extern crate doubter;
generate_doc_tests! {
include = "README.md",
include = "docs/**/*.md",
}
The macro generate_doc_tests!(...)
takes a comma-separated list of fields.
The following field keys are currently supported:
include
- string
A glob pattern that points to the path to the Markdown file(s) to be tested. Required to be a relative path from cargo's manifest directory.mode
- string, optional
The mode to convert Markdown files to doctest. Supported values are as follows:"raw"
(default) : embeds the Markdown files in Rust source as it is."extract"
: extracts code blocks and emit as doctest per blocks.
use_external_doc
- string or boolean, optional
Specify whether to use#[doc(include = "...")]
to embed Markdown files. When this filed is enabled, the value ofmode
is forced to"raw"
.
Currently, the implementation of function style procedural macro is using
proc-macro-hack
. The definition of procedural macro via custom Derive has some restrictions and theuse
-style import does not work as expected. You can switch the implementation to the Macros 1.2 by disabling the feature flaghack
(this feature flag is enabled by default):[dependencies.doubter] version = "0.1.0" default-features = false
See the test crates inside of crates/
.
doubter
is released under the MIT license.