从Rust代码中收集文档

这个小辅助库包含一个CollectDocs派生宏。将其添加到您的结构体中，如下所示

/// Very essential type to our application
#[example(
    yaml,
    "
    bar: 42
    baz:
      great_examples_so_far: 2
    "
)]
#[derive(Debug, serde::Deserialize, CollectDocs)]
pub struct Foo {
    /// Amount of pressure to apply
    ///
    /// CAUTION: Will be renamed to appropriate SI unit in next release.
    pub bar: usize,
    /// Description of this Foo
    #[example(
        yaml,
        "
    baz:
      great_examples_so_far: 2
    "
    )]
    pub baz: HashMap<String, i32>,
}

这将生成一个名为Foo.adoc的AsciiDoc文件（使用结构体名称）。默认情况下，它将写入./docs/generated，但您可以通过设置环境变量COLLECT_DOCS_TARGET来更改它。

渲染的文档看起来像这个，可以包含在您的AsciiDoc文档中。

示例

示例被添加到单独的属性中，指定文件类型后跟内容。它们将作为包含标题“示例”的代码块包含。

测试

YAML格式的示例还将转换为测试，以检查给定的内容是否可以通过示例中的项目进行解析。对于结构体，您应该提供结构体的全部内容；对于字段，您还需要包括serde期望的格式化中的字段名称（即，尊重#[serde)]）。

running 2 tests
test test_Foo_baz_example_0 ... ok
test test_Foo_example_0 ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

注意：您需要将serde和serde_yaml添加到自己的依赖中。

许可证

根据以下任一许可证授权：

• Apache许可证第2版 (LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0)
• MIT许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

任选其一。

贡献

除非您明确声明，否则根据Apache-2.0许可证定义的您提交给工作的任何贡献，都将根据上述方式双重许可，不附加任何额外条款或条件。