1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188
/*! * A very simple document model and set of markup wriers. * * This crate provides a simple document [`model`](model/index.html) 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`](write/index.html) * 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 * * ```rust * 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::from(HyperLink::external_with_caption_str( * "https://img.shields.io/badge/license-mit-118811.svg", * "MIT License", * ))) * .add_image(Image::from(HyperLink::external_with_caption_str( * "https://img.shields.io/badge/Min%20Rust-1.40-green.svg", * "Build", * ))) * .add_image(Image::from(HyperLink::external_with_caption_str( * &format!( * "https://github.com/{}/{}/workflows/Rust/badge.svg", * repo_owner, repo_name * ), * "Minimum Rust Version", * ))) * .add_image(Image::from(HyperLink::external_with_caption_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::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`](html/index.html), [`json`](json/index.html), * [`latex`](latex/index.html), and [`markdown`](markdown/index.html). * * 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`](read/index.html) 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](https://spec.commonmark.org/0.29/) spec. * * ```rust * # use somedoc::model::Document; * use somedoc::write::write_document_to_string; * use somedoc::write::markdown::MarkdownFlavor; * * # fn make_some_document() -> Document { Document::default() } * 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](https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiSyntax/) * markup format. * * ```rust * # use somedoc::model::Document; * use somedoc::write::{write_document_to_string, OutputFormat}; * use somedoc::write::markdown::MarkdownFlavor; * * # fn make_some_document() -> Document { Document::default() } * let doc = make_some_document(); * * let doc_str = write_document_to_string(&doc, MarkdownFlavor::XWiki.into()).unwrap(); * println!("{}", doc_str); * ``` * * ```rust * # use somedoc::model::Document; * use somedoc::write::{write_document_to_string, OutputFormat}; * * # fn make_some_document() -> Document { Document::default() } * 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. */ // ------------------------------------------------------------------------------------------------ // Preamble // ------------------------------------------------------------------------------------------------ #![warn( // ---------- Stylistic future_incompatible, nonstandard_style, rust_2018_idioms, trivial_casts, trivial_numeric_casts, // ---------- Public missing_debug_implementations, missing_docs, unreachable_pub, // ---------- Unsafe unsafe_code, // ---------- Unused unused_extern_crates, unused_import_braces, unused_qualifications, unused_results, )] #[macro_use] extern crate error_chain; #[macro_use] extern crate lazy_static; // ------------------------------------------------------------------------------------------------ // Modules // ------------------------------------------------------------------------------------------------ #[doc(hidden)] #[macro_use] pub mod macros; pub mod error; pub mod model; #[cfg(feature = "fmt_json")] pub mod read; pub mod write;