somedoc/lib.rs
1/*!
2* A very simple document model and set of markup wriers.
3*
4* This crate provides a simple document [`model`](model/index.html) that captures structure of simple documents. This is
5* not an all-purpose model, it does not have the richness of full document systems but is intended
6* for tools that simply need to generate useful documentation or reports.
7*
8* The model can then be serialized into specific formats using the formatters in the [`write`](write/index.html)
9* module. Currently various flavors of Markdown are implemented as well as the XWiki format.
10*
11* ## Model
12*
13* The `somedoc::model` module provides the model to construct documents.
14*
15* ### Example
16*
17* ```rust
18* use somedoc::model::block::{HasBlockContent, Heading, List, Paragraph};
19* use somedoc::model::document::Document;
20* use somedoc::model::inline::{HasInlineContent, HyperLink, Image, Span};
21*
22* fn readme_maker(crate_name: &str, repo_owner: &str, repo_name: &str, headline: &str) -> Document {
23* let tbd = Paragraph::plain_str("TBD");
24* let mut doc = Document::default();
25*
26* doc.add_heading(Heading::section(&format!("Crate {}", crate_name)))
27* .add_paragraph(Paragraph::plain_str(headline));
28*
29* let mut para = Paragraph::default();
30* para.add_image(Image::with_alt_text(
31* "https://img.shields.io/badge/license-mit-118811.svg",
32* "MIT License",
33* ))
34* .add_image(Image::with_alt_text(
35* "https://img.shields.io/badge/Min%20Rust-1.40-green.svg",
36* "Build",
37* ))
38* .add_image(Image::with_alt_text(
39* &format!(
40* "https://github.com/{}/{}/workflows/Rust/badge.svg",
41* repo_owner, repo_name
42* ),
43* "Minimum Rust Version",
44* ))
45* .add_image(Image::with_alt_text(
46* &format!(
47* "https://github.com/{}/{}/workflows/Security%20audit/badge.svg",
48* repo_owner, repo_name
49* ),
50* "Audit",
51* ));
52*
53* doc.add_paragraph(para)
54* .add_thematic_break()
55* .add_paragraph(tbd.clone())
56* .add_heading(Heading::sub_section("Example"))
57* .add_paragraph(tbd.clone())
58* .add_heading(Heading::sub_section("Features"))
59* .add_paragraph(tbd.clone())
60* .add_thematic_break()
61* .add_heading(Heading::sub_section("Changes"))
62* .add_paragraph(Paragraph::bold_str("Version 0.1.0"));
63*
64* let mut list = List::default();
65* list.add_item_from(Span::plain_str("Initial release.").into());
66*
67* doc.add_list(list)
68* .add_heading(Heading::sub_section("Issues"))
69* .add_paragraph(tbd.clone());
70*
71* doc
72* }
73* ```
74*
75* ## Writers
76*
77* The `somedoc::write` module contains a number of serializers that generate specific markup for
78* different platforms [`html`](html/index.html), [`json`](json/index.html),
79* [`latex`](latex/index.html), and [`markdown`](markdown/index.html).
80*
81* The JSON module is rather different from the rest, it is intended for tool usage and is a
82* direct representation of the `Document` model so that other tools may consume it. To read this
83* format the [`read`](read/index.html) module provides for parsing from a string value of from
84* a `std::io::Read` implementation.
85*
86* ### Examples
87*
88* The following writes a constructed document to `stdout` as a Markdown document. The default
89* flavor supported by the writer is the [CommonMark](https://spec.commonmark.org/0.29/) spec.
90*
91* ```rust
92* # use somedoc::model::Document;
93* use somedoc::write::write_document_to_string;
94* use somedoc::write::markdown::MarkdownFlavor;
95*
96* # fn make_some_document() -> Document { Document::default() }
97* let doc = make_some_document();
98*
99* let doc_str = write_document_to_string(&doc, MarkdownFlavor::default().into()).unwrap();
100* println!("{}", doc_str);
101* ```
102*
103* The following writes the same document out in the
104* [XWiki](https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiSyntax/)
105* markup format.
106*
107* ```rust
108* # use somedoc::model::Document;
109* use somedoc::write::{write_document_to_string, OutputFormat};
110* use somedoc::write::markdown::MarkdownFlavor;
111*
112* # fn make_some_document() -> Document { Document::default() }
113* let doc = make_some_document();
114*
115* let doc_str = write_document_to_string(&doc, MarkdownFlavor::XWiki.into()).unwrap();
116* println!("{}", doc_str);
117* ```
118*
119* ```rust
120* # use somedoc::model::Document;
121* use somedoc::write::{write_document_to_string, OutputFormat};
122*
123* # fn make_some_document() -> Document { Document::default() }
124* let doc = make_some_document();
125*
126* let doc_str = write_document_to_string(&doc, OutputFormat::Html).unwrap();
127* println!("{}", doc_str);
128* ```
129*
130* ## Features
131*
132* * Formats:
133* * **fmt_html** - HTML writer.
134* * **fmt_latex** - LaTeX (experimental) writer.
135* * **fmt_markdown** - Markdown/wiki writer.
136* * **emoji_names**; adds a new module `emoji_names` to `model::inline` which only contains string
137* constants for commonly supported emoji names. These can then be used to construct `Emoji` values
138* for inline characters. This feature is not included by default.
139* * **math_builder**; - experimental support for building math expressions. This feature is not
140* included by default.
141*/
142
143// ------------------------------------------------------------------------------------------------
144// Preamble
145// ------------------------------------------------------------------------------------------------
146
147#![warn(
148 // ---------- Stylistic
149 future_incompatible,
150 nonstandard_style,
151 rust_2018_idioms,
152 trivial_casts,
153 trivial_numeric_casts,
154 // ---------- Public
155 missing_debug_implementations,
156 missing_docs,
157 unreachable_pub,
158 // ---------- Unsafe
159 unsafe_code,
160 // ---------- Unused
161 unused_extern_crates,
162 unused_import_braces,
163 unused_qualifications,
164 unused_results,
165)]
166
167#[macro_use]
168extern crate error_chain;
169
170#[macro_use]
171extern crate lazy_static;
172
173// ------------------------------------------------------------------------------------------------
174// Modules
175// ------------------------------------------------------------------------------------------------
176
177#[doc(hidden)]
178#[macro_use]
179pub mod macros;
180
181pub mod error;
182
183pub mod model;
184
185#[cfg(feature = "fmt_json")]
186pub mod read;
187
188pub mod write;