Docify

这个crate提供了一组简单的Rust宏，即#[docify::export]和docify::embed!，它们允许您将当前crate或当前crate的子crate中的测试和示例动态嵌入到Rust文档注释中，并且可以选择使这些示例可执行。

docify的目的是允许您直接在文档中展示您最好的示例和测试，而不必在每次更改时更新两个地方。它还鼓励一种方法，即crate作者更好地记录他们的测试，因为他们现在可以直接在文档注释中展示这些测试。

总的来说，这比将文档示例孤立在文档中要好得多，因为您可以直接避免周围代码的模板代码，只需关注展示您想突出的项目。

通用用法

使用 docify 很简单。首先，使用 #[docify::export] 标记您希望嵌入的测试/示例/项目，如下所示

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

然后，您可以使用 docify::embed 宏直接在文档注释中嵌入此项目

/// 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!("source/file/path.rs", some_example)]
/// More docs can go here, the example will embed itself inline exactly
/// where you reference it.
pub struct SomeItem;

这将生成以下扩展文档注释

/// 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;

您可以将任何可以附加属性宏的项目嵌入。

可执行示例

请注意，您还可以使用embed_run!版本的宏来使嵌入式示例作为文档测试的一部分进行编译/运行，这在某些情况下是有益的，尽管通常示例已经在项目的其他地方运行/编译。

Markdown

新增功能允许编译包含正则docify::embed!(..)调用的HTML注释的Markdown文件，可以选择编译整个目录的文件或单个文件。

fn some_example() {
    assert_eq!(2 + 2, 4);
    assert_eq!(2 + 3, 5);
    assert_eq!(3 + 3, 6);
}

<!-- docify::embed!("examples/samples.rs", some_example) -->