Crate somedoc

A very simple document model and set of markup wriers.

This crate provides a simple document model that captures structure of simple documents. This is not an all-purpose model, it does not have the richness of full document systems but is intended for tools that simply need to generate useful documentation or reports.

The model can then be serialized into specific formats using the formatters in the write module. Currently various flavors of Markdown are implemented as well as the XWiki format.

Model

The somedoc::model module provides the model to construct documents.

Example

use somedoc::model::block::{HasBlockContent, Heading, List, Paragraph};
use somedoc::model::document::Document;
use somedoc::model::inline::{HasInlineContent, HyperLink, Image, Span};

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::section(&format!("Crate {}", crate_name)))
        .add_paragraph(Paragraph::plain_str(headline));

    let mut para = Paragraph::default();
    para.add_image(Image::with_alt_text(
        "https://img.shields.io/badge/license-mit-118811.svg",
        "MIT License",
    ))
    .add_image(Image::with_alt_text(
        "https://img.shields.io/badge/Min%20Rust-1.40-green.svg",
        "Build",
    ))
    .add_image(Image::with_alt_text(
        &format!(
            "https://github.com/{}/{}/workflows/Rust/badge.svg",
            repo_owner, repo_name
        ),
        "Minimum Rust Version",
    ))
    .add_image(Image::with_alt_text(
        &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::sub_section("Example"))
        .add_paragraph(tbd.clone())
        .add_heading(Heading::sub_section("Features"))
        .add_paragraph(tbd.clone())
        .add_thematic_break()
        .add_heading(Heading::sub_section("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::sub_section("Issues"))
        .add_paragraph(tbd.clone());

    doc
}

Writers

The somedoc::write module contains a number of serializers that generate specific markup for different platforms html, json, latex, and markdown.

The JSON module is rather different from the rest, it is intended for tool usage and is a direct representation of the Document model so that other tools may consume it. To read this format the read module provides for parsing from a string value of from a std::io::Read implementation.

Examples

The following writes a constructed document to stdout as a Markdown document. The default flavor supported by the writer is the CommonMark spec.

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

The following writes the same document out in the XWiki markup format.

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

let doc = make_some_document();

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

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

let doc = make_some_document();

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

Features

• Formats:
  • fmt_html - HTML writer.
  • fmt_latex - LaTeX (experimental) writer.
  • fmt_markdown - Markdown/wiki writer.
• emoji_names; adds a new module emoji_names to model::inline which only contains string constants for commonly supported emoji names. These can then be used to construct Emoji values for inline characters. This feature is not included by default.
• math_builder; - experimental support for building math expressions. This feature is not included by default.

Modules

error	Common Error, ErrorKind, and Result types.
model	The document model here comprises a document type with nested blocks comprised of blocks and inline content.
read	This module introduces the ability to read the JSON representation used for external tool integration.
write	Provides the functions, and format types, to serialize a Document in supported markup formats.