Merge branch 'api_redesign' into development

Cargo.toml

@@ -12,6 +12,8 @@ edition = "2021"
 keywords = ["template", "multi-template", "tera", "markup", "jinja2"]
 categories = ["template-engine"]
 rust-version = "1.71.0"
+homepage = "https://github.com/elmordo/terarium"
+repository = "https://github.com/elmordo/terarium"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 

README.md

@@ -12,6 +12,23 @@ cargo install terarium
 
 ## Usage
 
+To create `Terarium` instance, use the `TerariumBuilder`. This builder is able to configure templates and groups and 
+when you add all items, call the `build()` method to retrieve the `Terarium` instance. When preparing `Template` 
+instances, you can add more than one content. Each content is bound to one language key. But language key can have 
+assigned more than one content.
+
+When instance is ready, call `render_template` or `render_group` to render single template or template group defined by 
+its key. Because the library have multi-language support, the language key has to be passed and optional fallback 
+language key. The fallback language is used when the primary language version of a template is not found.
+
+Render result of the single template render is `Result<String, TerariumError>` where the `String` is the rendered 
+content.
+
+Render result of the template group render is `Result<HashMap<String, String>, TerariumError>` Where the `HashMap` 
+contains the data. Keys of the hashmap is group member keys and values are their rendered contents.
+
+## Example
+
 ```rust
 use tera::Context;
 use terarium::{Template, TemplateGroupBuilder, TerariumBuilder};
@@ -56,6 +73,7 @@ fn main() {
     ctx.insert("sender", "Jara Cimrman");
     ctx.insert("username", "Karel Capek");
 
+    // HashMap with group member names as keys and rendered contents as values
     let rendered_group_en = terarium.render_group(&ctx, "greet_email", "en", None).unwrap();
     let rendered_group_cs = terarium.render_group(&ctx, "greet_email", "cs", None).unwrap();
 

examples/fallback_language.rs

@@ -0,0 +1,19 @@
+use tera::Context;
+use terarium::{Template, TerariumBuilder};
+
+
+/// When primary language is missing, the fallback language can be used.
+fn main() {
+    let terarium = TerariumBuilder::default()
+        .add_template(
+            "my_template".to_owned(),
+            Template::default().content_builder()
+                .add_content("This is english template, because no czech template is available".to_owned(), vec!["en".to_owned()])
+                .build()
+        )
+        .build().unwrap();
+
+    // The EN template will be rendered
+    let result = terarium.render_template(&Context::new(), "my_template", "cs", Some("en")).unwrap();
+    println!("{}", result);
+}

examples/render_email.rs

@@ -1,6 +1,7 @@
 use tera::Context;
 use terarium::{Template, TemplateGroupBuilder, TerariumBuilder};
 
+/// The Terarium can create logical template groups and render them together,
 fn main() {
     let terarium = TerariumBuilder::<String>::default()
         .add_template(

examples/render_single_template.rs

@@ -0,0 +1,27 @@
+use tera::Context;
+use terarium::{Template, TerariumBuilder};
+
+/// The Terarium can render single template.
+fn main() {
+    let terarium = TerariumBuilder::default()
+        .add_template(
+            "my_template".to_owned(),
+            Template::default().content_builder()
+                .add_content("This is my template #{{tpl_number}}".to_owned(), vec!["en".to_owned()])
+                .add_content("Toto je šablona #{{tpl_number}}".to_owned(), vec!["cs".to_owned()])
+                .build()
+        )
+        .build().unwrap();
+
+    let mut ctx = Context::new();
+    ctx.insert("tpl_number", "13");
+
+    let output_en = terarium.render_template(&ctx, "my_template", "en", None).unwrap();
+    let output_cs = terarium.render_template(&ctx, "my_template", "cs", None).unwrap();
+
+    println!("\nEnglish:\n");
+    println!("{}\n", output_en);
+
+    println!("\nCzech:\n");
+    println!("{}\n", output_cs);
+}

src/templates.rs

@@ -17,6 +17,8 @@ pub struct Template<LanguageKey> {
 }
 
 
+/// Represent one template. The template has one or more contents. These contents are usually the same but in different
+/// languages. Each content can be assigned only to one language but one language can has more then one contents.ash
 impl<LanguageKey> Template<LanguageKey> where LanguageKey: Eq + Hash + Clone {
     /// Consume self and return the `ContentBuilder`
     pub fn content_builder(self) -> ContentBuilder<LanguageKey> {

src/terarium.rs

@@ -9,9 +9,9 @@ use thiserror::Error;
 use crate::Template;
 
 
-/// Group templates and render single templates or template groups.
-/// Multi-language  support is provided by the Terarium.
-/// The generic parameter is type of template/group/language key
+/// Wrapper over the `Tera` templating engine with capability of template bulk rendering.
+/// Each template can exists in more than one version (support for multi-language templates).
+/// An instance of the `Terarium` is built with the `TerariumBuilder`.
 pub struct Terarium<KeyType>
     where
         KeyType: Eq + Hash + Clone,
@@ -117,6 +117,7 @@ impl From<TeraError> for TerariumError {
 }
 
 
+/// Build the `Terarium` instance.
 #[derive(Default)]
 pub struct TerariumBuilder<KeyType>
     where
@@ -127,7 +128,6 @@ pub struct TerariumBuilder<KeyType>
 }
 
 
-/// Incremental build of the `Terarium` instances
 impl<KeyType> TerariumBuilder<KeyType>
     where
         KeyType: Eq + Hash + Clone,