Include Doc

Include examples in your Rustdocs.

Features

• Write and maintain your examples in a normal Rust file, with full editor support.
• Automatically hide imports.
• Put many examples into one file, and choose the parts of the file to include. This helps avoid duplicated boilerplate for imports and setup code.

See the crate docs for examples.

lib.rs:

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:

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

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:

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:

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