Atelier: crate atelier_describe

提供为 Smithy 模型编写文档的能力。

此crate提供两种机制，使用crate somedoc 生成Smithy模型的可读文档。

首先，DocumentationWriter 结构实现了 atelier_core::io::ModelWriter trait，因此可以使用与其他模型编写器相同的方式进行使用。 ModelWriter::new 函数接收一个参数，表示要生成的格式，但提供很少的控制来生成。在内部，此编写器实现调用以下函数。

describe_model 函数将根据 atelier_core::modrel::Model 生成一个 somedoc::model::Document 实例。然后，可以使用somedoc提供的编写器进行渲染。这提供了对实际格式化步骤的完全控制，并且如果需要，可以多次写入生成的文档。

示例

以下演示了如何使用 describe_model 函数。

use atelier_core::model::Model;
use atelier_describe::describe_model;
use somedoc::write::{write_document_to_string, OutputFormat};

let model = make_model();

let documentation = describe_model(&model).unwrap();

let doc_string = write_document_to_string(&documentation, OutputFormat::Html).unwrap();

以下示例演示了 ModelWriter trait 并输出文档，格式为 CommonMark，到标准输出。

use atelier_core::model::Model;
use atelier_core::io::ModelWriter;
use atelier_describe::DocumentationWriter;
use std::io::stdout;

let model = make_model();

let mut writer = DocumentationWriter::default();

let documentation = writer.write(&mut stdout(), &model).unwrap();

更改

版本 0.1.10

• 为成员形状添加了对 HasIdentity trait 的使用。

版本 0.1.9

• 将 MemberShape 的 ID 从 ShapeID 改为 Identifier。这既符合 Smithy IDL 的正式 BNF，也符合 JSON AST 的用法。

版本 0.1.8

• 完成了所有形状/成员的特型表。
• 为成员定义添加了一些额外的格式化，以增加缩进。

版本 0.1.7

• 支持在抽象模型中添加到服务形状的 "renames" 集合。

版本 0.1.6

• 支持核心模型构建器，现在使用 TryFrom 而不是 From。
• 使用新的共享 atelier-test crate。

版本 0.1.5

• 重构以具有与其他读者/写入器 crate 相似的结构。
• 将 GraphML 和 PlantUML 从 lib 移动到这个 crate 中。

版本 0.1.4

• 由于核心中的特型 API 更改而更新。

版本 0.1.3

• 重构 DocumentationWriter，使其仅输出 CommonMark，与 Smithy IDL 更为紧密地匹配。

版本 0.1.1

• 修复：提高了 somedoc 依赖项的版本。

版本 0.1.1

• 修复：移除了 somedoc 的本地路径依赖。

版本 0.1.0

这个初始版本尽管不完整，但基本可用。

待办事项

1. 完成预置和自定义特型输出。
2. 测试用例。