include_doc/
lib.rs

1//! Include Rust source files as doctests.
2//!
3//! # Examples
4//!
5//! ## Using [`source_file!`]
6//!
7//! We'll write our example in the file `examples/my_example.rs`, and use
8//! [`source_file!`] to add the example to our documentation. The contents of
9//! `examples/my_example.rs` are:
10//!
11//! ```
12#![doc = include_str!("../examples/my_example.rs")]
13//! ```
14//! 
15//! Using `#[doc = source_file!("examples/my_example.rs")]` will hide imports and
16//! include the body of the main function, leaving us with:
17//! ```
18#![doc = source_file!("examples/my_example.rs")]
19//! ```
20//! 
21//! ## Using [`function_body!`]
22//!
23//! [`function_body!`] is similar to [`source_file!`], but allows us to specify which
24//! function body to use as the doctest. This reduces boilerplate for imports
25//! and supporting code, as we can put many examples in one file. We can
26//! also specify which parts of the supporting code to include.
27//!
28//! Usage is:
29//! ```
30//! include_doc::function_body!(
31//!     "example.rs",
32//!     example_fn,
33//!     [fn_dependency, StructDependency, etc]
34//! );
35//! ```
36//! 
37//! In `tests/doc.rs`, we've put 2 examples, `my_first_example` and `my_second_example`.
38//! There are 2 different setup functions, but both use `MyStruct`. Here's the contents of
39//! `tests/doc.rs`:
40//! ```
41#![doc = include_str!("../tests/doc.rs")]
42//! ```
43//! 
44//! We want to include only the example code and dependencies for
45//! `my_first_example`, so we write
46//! `#[doc = function_body!("tests/doc.rs", my_first_example, [MyStruct, setup_first_example])]`,
47//! giving us:
48//! ```
49#![doc = function_body!("tests/doc.rs", my_first_example, [MyStruct, setup_first_example])]
50//! ```
51//! 
52//! For `my_second_example`, we use
53//! `#[doc = function_body!("tests/doc.rs", my_second_example, [MyStruct, setup_second_example])]`,
54//! giving:
55//! ```
56#![doc = function_body!("tests/doc.rs", my_second_example, [MyStruct, setup_second_example])]
57//! ```
58
59/// Include the function body from a Rust file as a doctest.
60///
61/// See [module][self] documentation.
62pub use include_doc_macro::function_body;
63/// Include a Rust file as a doctest.
64///
65/// See [module][self] documentation.
66pub use include_doc_macro::source_file;