Crate someDOC

一个非常简单的文档模型和标记生成器。

模型

somedoc::model 模块提供了构建文档的模型。

示例

fn readme_maker(crate_name: &str, repo_owner: &str, repo_name: &str, headline: &str) -> Document {
    let tbd = Paragraph::plain_str("TBD");
    let mut doc = Document::default();

    doc.add_heading(Heading::heading_1(&format!("Crate {}", crate_name)))
        .add_paragraph(Paragraph::plain_str(headline));

    let mut para = Paragraph::default();
    para.add_image(Image::new(HyperLink::external_with_label_str(
        "https://img.shields.io/badge/license-mit-118811.svg",
        "MIT License",
    )))
    .add_image(Image::new(HyperLink::external_with_label_str(
        "https://img.shields.io/badge/Min%20Rust-1.40-green.svg",
        "Build",
    )))
    .add_image(Image::new(HyperLink::external_with_label_str(
        &format!(
            "https://github.com/{}/{}/workflows/Rust/badge.svg",
            repo_owner, repo_name
        ),
        "Minimum Rust Version",
    )))
    .add_image(Image::new(HyperLink::external_with_label_str(
        &format!(
            "https://github.com/{}/{}/workflows/Security%20audit/badge.svg",
            repo_owner, repo_name
        ),
        "Audit",
    )));

    doc.add_paragraph(para)
        .add_thematic_break()
        .add_paragraph(tbd.clone())
        .add_heading(Heading::heading_2("Example"))
        .add_paragraph(tbd.clone())
        .add_heading(Heading::heading_2("Features"))
        .add_paragraph(tbd.clone())
        .add_thematic_break()
        .add_heading(Heading::heading_2("Changes"))
        .add_paragraph(Paragraph::bold_str("Version 0.1.0"));

    let mut list = List::default();
    list.add_item_from(Span::plain_str("Initial release.").into());

    doc.add_list(list)
        .add_heading(Heading::heading_2("Issues"))
        .add_paragraph(tbd.clone());

    doc
}

编写者

somedoc::write 模块包含了一系列序列化器，用于生成针对不同平台的特定标记格式。到目前为止，这包括 HTML、LaTeX 和不同风格的 Markdown。

JSON 交换

还提供了库的 Document 结构的 JSON 表示形式，可以读取和写入，以便进行工具交换。

示例

以下将构建的文档作为 Markdown 文档写入 stdout。编写器的默认支持格式是 CommonMark 规范。

use somedoc::write::write_document_to_string;
use somedoc::write::markdown::MarkdownFlavor;

let doc = make_some_document();

let doc_str = write_document_to_string(&doc, MarkdownFlavor::default().into()).unwrap();
println!("{}", doc_str);

以下将相同的文档以 XWiki 标记形式输出。

use somedoc::write::{write_document_to_string, OutputFormat};

let doc = make_some_document();

let doc_str = write_document_to_string(&doc, OutputFormat::XWiki).unwrap();
println!("{}", doc_str);

变更

版本 0.2.10

新增：在 CommonMark 中使用基本的 HTML 输出表格。

版本 0.2.9

修复：使用 id 宏在 XWiki 输出中对锚进行标记。

版本 0.2.8

修复：从 XWiki 输出的表格行中删除了尾随的 '|'。

版本 0.2.7

• 测试：测试 to_string 和 from_str 功能对于 OutputFormat。
  • OutputFormat 现在委托添加和解析风味。

版本 0.2.6

• 测试：更好的链接测试。
• 修复：非 XWiki Markdown 的链接输出。
• 修复：HTML 的链接输出。
• 修复：HTML 中的 关闭 标签没有。
• 修复：XWiki 编写器没有正确地进行换行。
• 修复：XWiki 换行。
• 重构：简化 Image 以拥有路径/inner 和 alt_text 字段。
  • 这减少了与链接和图像上的标题混淆。
  • 新增：向 Image 添加辅助函数和构造函数。
• 新增：添加了Label::copy_from构造函数。
• 新增：从HasInlineContent中添加了缺失的math和add_math函数。
• 新增：为Math添加了缺失的Into<BlockContent>。

版本 0.2.5

• 测试：添加了对标签、段落对齐、图像、数学、块引用和一些文本样式的测试。
• 测试：添加了对剩余Markdown语法的测试。
• 新增：为HasBlockContent特性添加了缺失的math和add_math函数。
• 新增：添加了新的序言元素，以正确布局和标注方程。
• 新增：为生成目录表添加了新的FrontMatter枚举。
• 新增：为Span添加了新的辅助函数。
• 修复：LaTeX编写器对图像块使用了错误的缩进。
• 修复：HTML编写器对图像和数学块使用了错误的缩进。
• 修复：Markdown编写器在块引用中交换了markdown/xwiki格式。

版本 0.2.4

• 修复：LaTeX编写器在内部引用时发出两个ref命令的bug。
• 修复：HTML编写器未为标签添加id属性的bug。
• 修复：LaTeX编写器未清除表格标题的bug。
• 修复：Label::is_valid匹配空格的bug。

版本 0.2.3

• 新增：添加了JSON编写器。
  • 添加了fmt_json功能。
  • 添加了对serde和serde_json的依赖。
  • 还向Document添加了version字段，以便进行工具检查，这将是写入时的crate版本。
  • 所有结构现在都支持Serde的Serialize/Deserialize。
• 添加了使用相同Serde支持的JSON读取器。

版本 0.2.2

• 新增：大部分完整的API库文档。
• 新增：inner_impl宏，用于一致地使用inner和into_inner方法。
  • 重构：这需要将link重命名为inner在Image上。
• 修复：在行内内容上的重复的From和from实现。
• 重构：将label重命名为text在model::block::table::Column。
• 重构：将Captioned特性重命名为HasCaption以保持一致性。
• 重构：将Text替换为Caption作为HyperLink标题的类型；也实现了HasCaption。
• 重构：定义列表仅有一个级别，术语仅是一个String。
• 重构：在Caption、Code、Formatted、Heading、Image中，用From<>替换仅接受单个值的构造函数。
• 重构：将new_with_函数重命名为简单的with_。
• 重构：移除 ParagraphStyle，将 alignment 作为单一值属性添加到 Paragraph。
  • 将对齐枚举移动到与其共享的模块，与 Paragraph 和 table::Column。
  • 添加了新的 HasAlignment 特性（和宏），以确保段落和列之间的兼容性。
• 清理：修复了所有的 Clippy 警告。

版本 0.2.1

这是一个重大更新，一些 API 将会改变，但计划是这些新的 API 形式将在 0.3.0 版本中得到稳定，这些版本可以用于非破坏性更改。

• 新增：HTML 编写器的额外功能。等待测试。
• 新增：LaTeX 的完整编写器实现。等待测试。
• 新增：为每个编写器添加配置功能，如 fmt_html、fmt_latex、fmt_markdown 等，默认功能包括所有这些。
• 新增：将 Writer 和 ConfigurableWriter 添加到 write 模块，以捕获编写器结构的实例化。
• 新增：更多库/API 文档，但并非全部。
• 重构：将所有类似 markdown 的格式合并到公共模块中。
• 重构：将 Anchor 类型移动到新的 Label，它不再是独立内联值，而是作为属性添加到大多数块类型。
• 重构：将 Abstract 从 Metadata 枚举中移出，并使其成为文档本身的属性。这也影响了访问者 API。
• 重构：将 HyperLink 上的 label/alt_text 重命名为 caption。
• 清理：简化了文档 API，移除了不必要的 Result<>。
• 清理：移除了对 log 的未使用依赖。
• 测试：添加了 pretty_assertions 依赖，以更好地比较测试失败。
• 测试：创建跨格式的测试用例。

版本 0.2.0

• 新增：新的访问者特性和将 XWiki 编写器迁移到使用它。
• 新增：使用新的访问者特性创建新的 HTML 编写器。
• 新增：新的 Math（内联）和 MathBlock（块）结构。
• 新增：为 Code、MathBlock 和 Table 添加新的 Caption 类型及其实现。
• 新增：为一些 String 新类型添加了 Deref（Anchor、Caption、Emoji 和 Text）。
• 测试：使用 proptest 对上述 String 新类型进行测试。

版本 0.1.7

• 修复：修复了在 HeadingLevel/markdown 生成中的错误。

版本 0.1.6

• 新增：开始编写库文档。
• 新增：添加了 model::inline::emoji_names 模块，但仅启用 emoji_names 功能。
• 新增：添加了 readme_maker 示例，此示例用于 README 和 lib.rs 文档。
• 修复：修复了 XWiki write_code 函数中的错误。
• 重构：文档元数据，以及 Markdown 编写器。
• 重构：将 TextStyle 重命名为 SpanStyle，并添加了 Sized 变体。
• 清理：由于当前为空，因此清理了 read 模块。
• 清理：也移除了 model::visitor 模块，因为改动过多，尚不稳定。
• 测试：一些初始测试用例。

版本 0.1.5（未发布）

• 为 XWiki 锚点添加了一些更多替换规则。

版本 0.1.4

• 将格式化 Anchor 的规则移入每个 writer。

版本 0.1.3

• 在 CodeBlock 旁边添加了 Formatted。
• 从 Markdown 和 XWiki writer 中移除了一些额外的空白行。

版本 0.1.2

• 修复了 XWiki writer 中的嵌套列表错误。

版本 0.1.1

• 为 git hooks 添加了 cargo-husky。
• 修复了 XWiki writer 中表格的错误。

版本 0.1.0

• 初始提交。基本模型工作正常，初始 Markdown 和 XWiki writer。