= Macros for including file content
Macros like `include_asciidoc!("../README.adoc", "example")` allow you to include incomplete code from AsciiDoc code fences.
Though Rust doc tests let you hide setup code from being rendered, you cannot do the same when rendering AsciiDoc.
You can demonstrate just the code you want in AsciiDoc while maintaining the benefit of compiling it in tests.
== Examples
The `include_asciidoc!()` macro resolves a file path relative to the directory containing the crate `Cargo.toml` manifest file.
Consider a crate `README.adoc` with the following content:
[,asciidoc]
----
The `example()` function returns a model that implements `Debug` so you can easily print it:
[,rust,id="example"]
let m = example()?;
assert_eq!(format!("{m:?}"), r#"Model { name: "example" }"#);
----
We didn't define the `example()` function nor the type of `m`.
In Rust doc tests you could do so with lines prefaced with `#`, but those lines would render in a markdown file.
Instead, we could use `include_asciidoc!("../README.adoc", "example")` to include the example content from `README.adoc` above in a test to make sure it compiles and even runs.
[,rust]
----
#[derive(Debug)]
struct Model {
name: String,
}
fn example() -> Result<Model, Box<dyn std::error::Error>> {
Ok(Model {
name: "example".into(),
})
}
#[test]
fn test_example() -> Result<(), Box<dyn std::error::Error>> {
include_markdown!("../README.adoc", "example");
Ok(())
}
----
[,rust,id="simple-assert"]
----
assert_eq!(1 + 1, 2);
----
[,rust,id="assert-fail"]
----
// Used by tests to verify that a panic in one snippet does not cause prior
// guards to print an additional "note:" line.
assert!(false, "intentional assert failure");
----
== License
Licensed under the link:../LICENSE.txt[MIT] license.