include_doc/
lib.rs

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