Crate docify

source ·
Expand description

Docify provides a simple set of rust macros, namely #[docify::export] and docify::embed!, that allow you to dynamically embed tests and examples at compile time from the current crate or sub-crates of the current crate directly within rust docs comments, with the option to make these examples runnable.

The intent behind docify is to allow you to showcase your best examples and tests directly in your docs, without having to update them in two places every time there is a change. It also encourages a methodology where crate authors better document their tests, since they can now showcase these directly in their doc comments.

All-in-all this is a much better workflow than having doc examples isolated within your docs, since you can avoid boilerplate from the surrounding code and just focus on showcasing the item you want to highlight.

§General Usage

Using docify is simple. First mark the tests/examples/items that you wish to embed with #[docify::export], such as the following:

#[docify::export]
fn some_example() {
    assert_eq!(2 + 2, 4);
    assert_eq!(2 + 3, 5);
    assert_eq!(3 + 3, 6);
}

You can then embed this item directly in doc comments using the docify::embed macro:

/// These are some docs about an item. You can embed examples, tests, and
/// other items directly into docs using the following macro:
#[doc = docify::embed!("examples/samples.rs", some_example)]
/// More docs can go here, the example will embed itself inline exactly
/// where you reference it.
pub struct SomeItem;

This will result in the following expanded doc comments:

/// These are some docs about an item. You can embed examples, tests, and
/// other items directly into docs using the following macro:
/// ```ignore
/// fn some_example() {
///     assert_eq!(2 + 2, 4);
///     assert_eq!(2 + 3, 5);
///     assert_eq!(3 + 3, 6);
/// }
/// ```
/// More docs can go here, the example will embed itself inline exactly
/// where you reference it.
pub struct SomeItem;

You can embed any item capable of having an attribute macro attached to it.

§Runnable Examples

Note that you can also use the embed_run! version of the macro to make the embedded example compile/run as part of doc tests, which is desirable in certain situations even though typically the example will already be running/compiling somewhere else in your project.

§Dynamic Embedding in Markdown Files

A newly added feature allows compiling entire directories of markdown files with HTML comments that contain regular docify::embed! calls. See compile_markdown! for more info.

There is a live example of this as well in README.md where this same sentence appears in the root of the repo. README.md is dynamically generated when cargo doc is run based on the contents of .README.docify.md.

Macros§

  • compile_markdown
    Allows you to use docify::embed!(..) within markdown source files via HTML comments and compiles the result for you (at compile-time).
  • embed
    Embeds the specified item from the specified source file in a rust doc example, with pretty formatting enabled.
  • embed_run
    Exactly like docify::embed!(..) in every way except the generated examples are also run automatically as rust doc examples (ignore is not included).

Attribute Macros§