7 releases

Uses old Rust 2015

0.1.0 Oct 15, 2018
0.0.6 Oct 14, 2018

#7 in #doctest

33 downloads per month
Used in 2 crates

MIT license

17KB
504 lines

doubter

crates.io Docs.rs Master Doc Rustc Version

Test Rust code blocks in your Markdown files.

Overview

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.

Getting Started

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

Using Procedural Macros

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 of mode 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 the use-style import does not work as expected. You can switch the implementation to the Macros 1.2 by disabling the feature flag hack (this feature flag is enabled by default):

[dependencies.doubter]
version = "0.1.0"
default-features = false

Examples

See the test crates inside of crates/.

Alternatives

License

doubter is released under the MIT license.

Dependencies

~2.5MB
~61K SLoC