Crate include_doc

source ·
Expand description

Include Rust source files as doctests.

Examples

Using source_file!

We’ll write our example in the file examples/my_example.rs, and use source_file! to add the example to our documentation. The contents of examples/my_example.rs are:

use std::println;

fn main() {
    println!("Hello world!");
}

Using #[doc = source_file!("examples/my_example.rs")] will hide imports and include the body of the main function, leaving us with:

println!("Hello world!");

Using function_body!

function_body! is similar to source_file!, but allows us to specify which function body to use as the doctest. This reduces boilerplate for imports and supporting code, as we can put many examples in one file. We can also specify which parts of the supporting code to include.

Usage is:

include_doc::function_body!(
    "example.rs",
    example_fn,
    [fn_dependency, StructDependency, etc]
);

In tests/doc.rs, we’ve put 2 examples, my_first_example and my_second_example. There are 2 different setup functions, but both use MyStruct. Here’s the contents of tests/doc.rs:

struct MyStruct;

fn setup_first_example(_: MyStruct) {}

fn setup_second_example(_: MyStruct) {}

pub fn my_first_example() {
    setup_first_example(MyStruct);
    println!("Hello, world!");
}

pub fn my_second_example() {
    setup_second_example(MyStruct);
    println!("Hello, world!");
}

We want to include only the example code and dependencies for my_first_example, so we write #[doc = function_body!("tests/doc.rs", my_first_example, [MyStruct, setup_first_example])], giving us:

struct MyStruct;

fn setup_first_example(_: MyStruct) {}

setup_first_example(MyStruct);
println!("Hello, world!");

For my_second_example, we use #[doc = function_body!("tests/doc.rs", my_second_example, [MyStruct, setup_second_example])], giving:

struct MyStruct;

fn setup_second_example(_: MyStruct) {}

setup_second_example(MyStruct);
println!("Hello, world!");

Macros