Macro docify::embed

embed!() { /* proc-macro */ }

Embeds the specified item from the specified source file in a rust doc example, with pretty formatting enabled.

Should be used in a #[doc = ...] statement, like the following:

/// some doc comments here
#[doc = docify::embed!("path/to/file.rs", my_example)]
/// more doc comments
struct DocumentedItem;

Which will expand to the my_example item in path/to/file.rs being embedded in a rust doc example marked with ignore. If you want to have your example actually run in rust docs as well, you should use docify::embed_run!(..).

Arguments

• source_path: the file path (relative to the current crate root) that contains the item you would like to embed, represented as a string literal. If you wish to embed an entire file, simply specify only a source_path with no other arguments and the entire file will be embedded as a doc example. If the path cannot be read for whatever reason, a compile error will be issued. The source_path does not have to be a file that is part of the current compilation unit, though typically it should be. The only requirement is that it must contain valid Rust source code, and must be a descendant of the current crate’s root directory. While embedding files from a parent directory of the current crate may work locally, this will fail when you go to deploy to crates.io and/or docs.rs, so you should not use ../ or similar means unless you plan to never deploy to these services.
• item_ident: (optional) can be specified after source_path, preceded by a comma. This should match the export name you used to #[docify::export(..)] the item, or, if no export name was specified, this should match the inherent ident/name of the item. If the item cannot be found, a compile error will be issued. As mentioned above, if no item_ident is specified, the entire file will be embedded as an example.

All items in the source_file exist in the same global scope when they are exported for embedding. Special care must be taken with how you #[docify::export(..)] items in order to get the item you want.

If there multiple items in a file that resolve to the same item_ident (whether as an inherent ident name or as a manually specified item_ident), and you embed using this ident, all matching items will be embedded, one after another, listed in the order that they appear in the source_file.

Here is an example of embedding an entire source file as an example:

/// Here is a cool example module:
#[doc = docify::embed!("examples/my_example.rs")]
struct DocumentedItem

You are also free to embed multiple examples in the same set of doc comments:

/// Example 1:
#[doc = docify::embed!("examples/example_1.rs")]
/// Example 2:
#[doc = docify::embed!("examples/example_2.rs")]
/// More docs
struct DocumentedItem;

Note that all examples generated by docify::embed!(..) are set to ignore by default, since they are typically already functioning examples or tests elsewhere in the project, and so they do not need to be run as well in the context where they are being embedded. If for whatever reason you do want to also run an embedded example as a doc example, you can use docify::embed_run!(..) which removes the ignore tag from the generated example but otherwise functions exactly like #[docify::embed!(..)] in every way.

Output should match rustfmt output exactly.