Finish the switch to teh askama templates

Author: msuchane

data/templates/assembly.adoc

@@ -33,19 +33,19 @@ The `context` attribute enables module reuse. Every module ID includes {context}
 ////
 
 [role="_abstract"]
-// <example>
+{% if examples -%}
 This paragraph is the assembly introduction. It explains what the user will accomplish by working through the modules in the assembly and sets the context for the user story the assembly is based on. The text that immediately follows the `[role="_abstract"]` tag is used for search metadata.
-// </example>
+{%- endif %}
 
 == Prerequisites
 
-// <example>
+{% if examples -%}
 * A bulleted list of conditions that must be satisfied before the user starts following this assembly.
 * You can also link to other modules or assemblies the user must follow before starting this assembly.
 * Delete the section title and bullets if the assembly has no prerequisites.
 * X is installed. For information about installing X, see <link>.
 * You can log in to X with administrator privileges.
-// </example>
+{%- endif %}
 
 ////
 The following include statements pull in the module files that comprise the assembly. Include any combination of concept, procedure, or reference modules required to cover the user story. You can also include other assemblies.
@@ -69,11 +69,11 @@ include::modules/TEMPLATE_PROCEDURE_reference-material.adoc[leveloffset=2]
 Optional. Delete if not used.
 ////
 
-// <example>
+{% if examples -%}
 * A bulleted list of links to other material closely related to the contents of the assembly, including xref links to other assemblies in your collection.
 * For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
-// </example>
+{%- endif %}
 
 ////
 Restore the context to what it was before this assembly.

data/templates/concept.adoc

@@ -18,25 +18,25 @@ In the title of concept modules, include nouns or noun phrases that are used in
 ////
 
 [role="_abstract"]
-// <example>
+{% if examples -%}
 Write a short introductory paragraph that provides an overview of the module. The text that immediately follows the `[role="_abstract"]` tag is used for search metadata.
 
 The contents of a concept module give the user descriptions and explanations needed to understand and use a product.
 
 * Look at nouns and noun phrases in related procedure modules and assemblies to find the concepts to explain to users.
 * Explain only things that are visible to users. Even if a concept is interesting, it probably does not require explanation if it is not visible to users.
 * Do not include any instructions to perform an action, such as executing a command. Action items belong in procedure modules.
-// </example>
+{%- endif %}
 
 [role="_additional-resources"]
 .Additional resources
 ////
 Optional. Delete if not used.
 ////
-// <example>
+{% if examples -%}
 * A bulleted list of links to other material closely related to the contents of the concept module.
 * Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module.
 * For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
-// </example>
+{%- endif %}
 

data/templates/procedure.adoc

@@ -16,53 +16,53 @@ Start the title of a procedure module with a verb, such as Creating or Create. S
 ////
 
 [role="_abstract"]
-// <example>
+{% if examples -%}
 Write a short introductory paragraph that provides an overview of the module. Procedure modules should include  the steps that users perform and address user motivation.The text that immediately follows the `[role="_abstract"]` tag is used for search metadata.
-// </example>
+{%- endif %}
 
 .Prerequisites
 
-// <example>
+{% if examples -%}
 * A bulleted list of conditions that must be satisfied before the user starts following this module.
 * You can also link to other modules or assemblies the user must follow before starting this module.
 * Delete the section title and bullets if the module has no prerequisites.
-// </example>
+{%- endif %}
 
 .Procedure
 
-// <example>
+{% if examples -%}
 . Start each step with an active verb.
 
 . Include one command or action for each step with the exception of simple follow-step, for example:
 .. Do this thing and then select *Next*.
 .. Do this other thing and then select *Next*.
 
 . Use an unnumbered bullet (*) if the procedure includes only one step.
-// </example>
+{%- endif %}
 
 .Verification
 ////
 Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure.
 ////
 
-// <example>
+{% if examples -%}
 . Start each step with an active verb.
 
 . Include one command or action per step.
 
 . Use an unnumbered bullet (*) if the procedure includes only one step.
-// </example>
+{%- endif %}
 
 
 [role="_additional-resources"]
 .Additional resources
 ////
 Optional. Delete if not used.
 ////
-// <example>
+{% if examples -%}
 * A bulleted list of links to other material closely related to the contents of the procedure module.
 * Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module.
 * For more details on writing procedure modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
-// </example>
+{%- endif %}
 

data/templates/reference.adoc

@@ -16,7 +16,7 @@ In the title of a reference module, include nouns that are used in the body text
 ////
 
 [role="_abstract"]
-// <example>
+{% if examples -%}
 Write a short introductory paragraph that provides an overview of the module. The text that immediately follows the `[role="_abstract"]` tag is used for search metadata. A reference module provides data that users might want to look up, but do not need to remember.
 It has a very strict structure, often in the form of a list or a table.
 A well-organized reference module enables users to scan it quickly to find the details they want.
@@ -38,17 +38,17 @@ Term 2:: Definition
 |Row 1, column 1|Row 1, column 2|Row 1, column 3
 |Row 2, column 1|Row 2, column 2|Row 2, column 3
 |====
-// </example>
+{%- endif %}
 
 [role="_additional-resources"]
 .Additional resources
 ////
 Optional. Delete if not used.
 ////
-// <example>
+{% if examples -%}
 * A bulleted list of links to other material closely related to the contents of the concept module.
 * Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module.
 * For more details on writing reference modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
-// </example>
+{%- endif %}
 

src/templating.rs

@@ -12,92 +12,78 @@ struct AssemblyTemplate<'a> { // the name of the struct can be anything
                    // in your template
     module_title: &'a str,
     include_statements: &'a str,
+    examples: bool,
 }
 
 #[derive(Template)]
 #[template(path = "concept.adoc", escape = "none")]
 struct ConceptTemplate<'a> {
     module_id: &'a str,
     module_title: &'a str,
+    examples: bool,
 }
 
 #[derive(Template)]
 #[template(path = "procedure.adoc", escape = "none")]
 struct ProcedureTemplate<'a> {
     module_id: &'a str,
     module_title: &'a str,
+    examples: bool,
 }
 
 #[derive(Template)]
 #[template(path = "reference.adoc", escape = "none")]
 struct ReferenceTemplate<'a> {
     module_id: &'a str,
     module_title: &'a str,
+    examples: bool,
 }
 
 
 impl Input {
-    /// Perform string replacements in the modular template that matches the `ModuleType`.
-    /// Return the template text with all replacements.
-    pub fn text(&self) -> String {
-        // TODO: Add a comment in the generated file with a pre-filled include statement
-
-        let mut template = match self.mod_type {
-            ModuleType::Assembly => AssemblyTemplate {
-                module_id: &self.id(),
-                module_title: &self.title,
-                include_statements: if let Some(include_statements) = &self.includes {
-                    /* include_statements.join("\n\n") */
-                    "Include this.\n\nInclude that."
-                } else {
-                    "Include modules here."
-                }
-            }.render(),
-            ModuleType::Concept => ConceptTemplate { module_id: &self.id(), module_title: &self.title }.render(),
-            ModuleType::Procedure => ProcedureTemplate { module_id: &self.id(), module_title: &self.title }.render(),
-            ModuleType::Reference => ReferenceTemplate { module_id: &self.id(), module_title: &self.title }.render(),
-        }.expect("Failed to cintruct the template");
-
-        /*
+    /// Render the include statements that appear inside an assembly
+    /// into the final format. If the assembly includes nothing, use
+    /// a placeholder, or an empty string if examples are disabled.
+    fn includes_block(&self) -> String {
         if let Some(include_statements) = &self.includes {
             // The includes should never be empty thanks to the required group in clap
             assert!(!include_statements.is_empty());
             // Join the includes into a block of text, with blank lines in between to prevent
             // the AsciiDoc syntax to blend between modules
-            let includes_text = include_statements.join("\n\n");
-
-            template_with_replacements =
-                template_with_replacements.replace("${include_statements}", &includes_text);
+            include_statements.join("\n\n")
         } else if self.options.examples {
-            template_with_replacements = template_with_replacements
-                .replace("${include_statements}", "Include modules here.");
+            "Include modules here.".to_string()
         } else {
-            template_with_replacements =
-                template_with_replacements.replace("${include_statements}\n", "");
+            String::new()
         }
-        */
+    }
 
-        // If the `--no-examples` option is active, remove all lines between the <example> tags.
-        if !self.options.examples {
-            let examples: Regex = RegexBuilder::new(r"^// <example>\n[\s\S]*\n^// </example>\n")
-                .multi_line(true)
-                .swap_greed(true)
-                .build()
-                .unwrap();
-            template = examples
-                .replace_all(&template, "")
-                .to_string();
-        // If the `--no-examples` option isn't active, remove just the <example> tags.
-        } else {
-            let example_tags: Regex = RegexBuilder::new(r"^// </?example>\n")
-                .multi_line(true)
-                .swap_greed(true)
-                .build()
-                .unwrap();
-            template = example_tags
-                .replace_all(&template, "")
-                .to_string();
-        }
+    /// Perform string replacements in the modular template that matches the `ModuleType`.
+    /// Return the template text with all replacements.
+    pub fn text(&self) -> String {
+        let mut document = match self.mod_type {
+            ModuleType::Assembly => AssemblyTemplate {
+                module_id: &self.id(),
+                module_title: &self.title,
+                include_statements: &self.includes_block(),
+                examples: self.options.examples,
+            }.render(),
+            ModuleType::Concept => ConceptTemplate {
+                module_id: &self.id(),
+                module_title: &self.title,
+                examples: self.options.examples,
+            }.render(),
+            ModuleType::Procedure => ProcedureTemplate {
+                module_id: &self.id(),
+                module_title: &self.title,
+                examples: self.options.examples,
+            }.render(),
+            ModuleType::Reference => ReferenceTemplate {
+                module_id: &self.id(),
+                module_title: &self.title,
+                examples: self.options.examples,
+            }.render(),
+        }.expect("Failed to construct the document from the template");
 
         // If comments are disabled via an option, delete comment lines from the content
         if !self.options.comments {
@@ -107,8 +93,8 @@ impl Input {
                 .swap_greed(true)
                 .build()
                 .unwrap();
-            template = multi_comments
-                .replace_all(&template, "")
+            document = multi_comments
+                .replace_all(&document, "")
                 .to_string();
 
             // Delete single-line comments
@@ -117,20 +103,22 @@ impl Input {
                 .swap_greed(true)
                 .build()
                 .unwrap();
-            template = single_comments
-                .replace_all(&template, "")
+            document = single_comments
+                .replace_all(&document, "")
                 .to_string();
 
             // Delete leading white space left over by the deleted comments
             let leading_whitespace: Regex = RegexBuilder::new(r"^[\s\n]*")
                 .multi_line(true)
                 .build()
                 .unwrap();
-            template = leading_whitespace
-                .replace(&template, "")
+            document = leading_whitespace
+                .replace(&document, "")
                 .to_string();
         }
 
-        template
+        // Add newlines at the end of the document to prevent potential issues
+        // when including two AsciiDoc files right next to each other.
+        document + "\n\n"
     }
 }